@github/openapi

@github/openapi

This project houses 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.

Contents

• What is OpenAPI?
• Installation
• Command line usage
• Programmatic usage
• Module API
• Downloads
• Contributing
• Contributors ✨

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.

Installation

This project is published to the npm registry at @github/openapi. If you're using Node.js, you can download and install the package using npm:

$ npm i @github/openapi

To download the raw JSON schema, see Downloads

Command line usage

The npm module includes a command line utility that outputs JSON schema data to STDOUT. The CLI can be installed globally with npm i -g @github/openapi or executed directly with npx.

Print usage info:

npx @github/openapi

Write a schema to disk and serve it with redoc-cli:

npx @github/openapi schema > schema.json
npx redoc-cli serve schema.json

List schema operations and filter output with json or jq:

# List all operations
npx @github/openapi operations

# List operation IDs
npx @github/openapi operations | json -a operationId
npx @github/openapi operations | jq '.[] | .operationId'

# View a single operation
npx @github/openapi operations | json 0
npx @github/openapi operations | jq '.[0]'

Programmatic 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()

Module 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'
// ]

Downloads

The compiled JSON schemas can be downloaded from unpkg.com/@github/openapi

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.

Contributing

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

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!