@github/openapi

openapi

OpenAPI schema for GitHub's REST API

This is a work in progress, owned by the @github/product-docs-engineering team. If you have questions, reach out to us in #docs-engineering on Slack.

Installation

This schema is published as a package on the npm registry:

npm install @github/openapi

If you're not using npm or Node.js, you can still consume the raw JSON schema files from unpkg.com/@github/openapi/

Usage

const github = require('@github/openapi')

// or:

const {schemas, getSchema, getOperation} = require('@github/openapi')

API

getOperations(schema)

Async function that returns an array of all operations for the given schema.

Parameters:

• schema Object, optional - a schema object. If no schema argument is supplied, the api.github.com schema will be loaded by default.

Example:

const operations = await github.getOperations()
console.log(operations[0])

{
  verb: 'get',
  requestPath: '/user/starred/{owner}/{repo}',
  parameters: [
    {
      name: 'accept',
      description: 'Setting to `application/vnd.github.v3+json` is recommended',
      in: 'header',
      schema: [Object]
    },
    ...
  ],
  ...
}

getSchema(schemaName)

Async function that returns a JS schema.

Parameters:

• schemaName String, optional - a string representing the shorthand schema name corresponding to one of the keys present in the schemas object. Alternatively, an HTTP(S) URL can be supplied to download a remote schema. If no argument is supplied, the api.github.com schema will be loaded by default.

Examples:

await getSchema() // returns `api.github.com-deref`
await getSchema('ghe-2.19-deref')
await getSchema('https://openapi.github.com/some-staging-schema.json')

schemas

An object containing multiple versions of the GitHub REST API schema for api.github.com and all currently supported versions of GitHub Enterprise Server.

Example:

console.log(Object.keys(github.schemas))

// [
//   'api.github.com-deref',
//   'api.github.com',
//   'ghe-2.16-deref',
//   'ghe-2.16',
//   'ghe-2.17-deref',
//   'ghe-2.17',
//   'ghe-2.18-deref',
//   'ghe-2.18',
//   'ghe-2.19-deref',
//   'ghe-2.19'
// ]

Staging builds

The bundled (with internal $ref pointers) or fully dereferenced OpenAPI documents can be downloaded from GitHub Pages. These files are published to GitHub Pages automatically using a GitHub Actions workflow whenever a pull request is merged.

Latest staging builds

• api.github.com: bundled, dereferenced
• GHE 2.15: bundled, dereferenced
• GHE 2.16: bundled, dereferenced
• GHE 2.17: bundled, dereferenced
• GHE 2.18: bundled, dereferenced

Per-commit versions

Use the following URLs to access a bundled or dereferenced OpenAPI document for a specific commit:

https://github.github.io/openapi/<short-commit-sha>/<api-version>.yml

where <short-commit-sha> is the short seven-character SHA1 of the corresponding commit and <api-version> can be one of:

• api.github.com or api.github.com-deref
• ghe-2.15 or ghe-2.15-deref
• ghe-2.16 or ghe-2.16-deref
• ghe-2.17 or ghe-2.17-deref
• ghe-2.18 or ghe-2.18-deref

To view all staging releases, see the gh-pages branch.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Roman Hotsiy 💻 📖 🤔 👀 💡

Gregor Martynus 💻 🖋 📖 🤔 👀

Zeke Sikelianos 🤔 👀

Sarah Schneider 👀

Marc-Andre Giroux 🤔

Keith Cirkel 🚇

This project follows the all-contributors specification. Contributions of any kind welcome!