extensions.md

OpenAPI Extensions

This document describes the OpenAPI 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.

The value should be a string.

Example usage

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.

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 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

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. The value should be a boolean. Defaults to false.

Example

- name: ref
  in: path
  required: true
  schema:
    type: string
  x-multi-segment: true