v0.0.1v0.0.1

1 files changed, 71 insertions, 0 deletions

diff --git a/extensions.md b/extensions.md
new file mode 100644
index 000000000..2e9ddef27
--- /dev/null
+++ b/extensions.md
@@ -0,0 +1,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:
+  enabledForApps: 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
+```