blob: fac9fcc8bb8de6dbb20f3c22b39632430f2cff99 (
plain) (
blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
|
# OpenAPI Extensions
This document describes the [OpenAPI extensions](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#specification-extensions) used in GitHub's REST API OpenAPI descriptions.
## `x-displayName`
### Purpose
To define a display name, typically for documentation interfaces, for the corresponding tag.
### Usage
This applies to the [Tag Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#tagObject).
The value should be a string.
#### Example usage
```yml
tags:
name: actions
description: Endpoints to manage GitHub Actions using the REST API.
x-displayName: GitHub Actions
```
## `x-github`
### Purpose
Provides extra information used to generate Octokit SDKs.
### Usage
The `x-github` specification extension is applied to the [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#operationObject).
| Field Name | Type | Description |
| :---------- | :------: | :----------- |
| triggersNotification | boolean | Operations that trigger notification are more likely to trigger abuse limits. We increase the default throttling from 1s between requests to 3s between requests for these operations. |
| deprecationDate | string | The date when we publicly announce that the operation will eventually be removed. After this date, the `deprecated` property should also be set to `true`. Format: `YYYY-MM-DD` |
| removalDate | string | The date when we stop displaying documentation for the operation on docs.github.com and stop including it in new Octokit major versions. Format: `YYYY-MM-DD` |
| githubCloudOnly | boolean | Used in a [separate plugin](https://github.com/octokit/plugin-enterprise-cloud.js/) for GitHub Enterprise Cloud users. |
| enabledForGitHubApps | boolean | True if this operation is enabled for apps |
| previews | array | Previews will be deprecated soon. An array of API previews, with name, description, and whether the preview is required for this particular operation. |
#### Example usage
```yml
x-github:
enabledForGitHubApps: true
githubCloudOnly: false
previews: []
```
## `x-multi-segment`
Path parameter extension marking a certain parameter as supporting multiple URL segments. It's recommended to use an URL encoded value when possible.
### Usage
The `x-multi-segment` extension applies only on [path parameters](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#parameter-object). The value should be a boolean. Defaults to false.
#### Example
```yml
- name: ref
in: path
required: true
schema:
type: string
x-multi-segment: true
```
|
