@github/openapi

openapi

OpenAPI schema for GitHub's REST API

This repo contains the official OpenAPI schemas for GitHub's REST API, including the api.github.com API and all currently supported GitHub Enterprise versions of the REST API.

What is OpenAPI?

OpenAPI (formerly Swagger) is an extension of JSON Schema that defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of an HTTP web service.

OpenAPI schemas are contracts that are useful both for API authors and API consumers. They can be used to produce API documentation, generate API clients (SDKs), run automated tests, validate API payloads, etc.

How it works

This git repository contains YAML files that are edited by humans. Each API operation lives in its own YAML file. To keep the source files DRY, these files make extensive use of JSON Schema $refs, which are re-usable references to other parts of the schema.

At build time, the schema files are compiled into standalone JSON files and published in an npm package. See Usage below for more details.

If you'd like to contribute to this project, please see CONTRIBUTING.md

Usage

The compiled JSON schemas can be consumed using the @github/openapi npm module or as raw JSON files which can be downloaded from unpkg.com/@github/openapi/.

First, install the module:

npm install @github/openapi

Then use it in your JavaScript project:

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

async function main () {
  // list all available schemas
  console.log(Object.keys(schemas))

  // load the api.github.com schema
  const schema = await getSchema('api.github.com-deref')

  // generate an array of operation objects from the schema
  const operations = await getOperations(schema)
  
  // list the unique names of all operations
  console.log(operations.map(operation => operation.operationId))
}

main()

API

getOperations(schema)

Async function that returns a Promise that resolves to 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 Promise that resolves to a JSON schema object.

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!