# @github/openapi

This project houses the official OpenAPI definitions for [GitHub's REST API](https://developer.github.com/v3), including the `api.github.com` API and all currently supported GitHub Enterprise versions of the REST API.

✋ Note! This project is under active development and is rapidly evolving. We use semantic versioning and [conventional commit messages](https://www.conventionalcommits.org/en/v1.0.0/) to ensure we're tracking breaking changes and releasing new major versions as necessary, but we cannot always be sure how changes might affect downstream consumers. If you are using these definitions, please be aware that they will change over time.

## Contents

- [What is OpenAPI?](#what-is-openapi)
- [Who's using this?](#whos-using-this)
- [Installation](#installation)
- [Programmatic usage](#programmatic-usage)
- [Module API](#api)
- [Command line usage](#command-line-usage)
- [Downloads](#downloads)
- [Contributing](#contributing)
- [Contributors ✨](#contributors-%E2%9C%A8)
  
## What is OpenAPI?

[OpenAPI](https://swagger.io/specification/) (formerly Swagger) is an extension of [JSON Schema](https://json-schema.org/) 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.

## Who's using this?

These definitions are used to generate GitHub's REST API reference documentation at [help.github.com/rest/reference](https://help.github.com/rest/reference).

These definitions will also soon be used to generate the [JavaScript](https://github.com/octokit/plugin-rest-endpoint-methods.js) and [Ruby](https://github.com/octokit/octokit.rb) Octokit client libraries. (This is a work in progress.)

## Installation

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

```sh
$ npm i @github/openapi
```

To download the raw JSON schema, see [Downloads](#downloads)

## 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/](https://unpkg.com/@github/openapi/dist/).

First, install the module:

```sh
npm install @github/openapi
```

Then use it in your JavaScript project:

```js
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:

```js
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:

```js
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:

```js
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'
// ]
```

## 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`](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b).

Print usage info:

```sh
npx @github/openapi
```

Write a schema to disk and serve it with [`redoc-cli`](https://github.com/Redocly/redoc/blob/master/cli/README.md):

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

List schema operations and filter output with [`json`](https://trentm.com/json) or [`jq`](https://stedolan.github.io/):

```sh
# 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]'
```

## Downloads

The compiled JSON schemas can be downloaded from [unpkg.com/@github/openapi](https://unpkg.com/@github/openapi/dist/)

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](https://github.github.io/openapi/latest/api.github.com.yml), [dereferenced](https://github.github.io/openapi/latest/api.github.com-deref.yml)
- `GHE 2.15`: [bundled](https://github.github.io/openapi/latest/ghe-2.15.yml), [dereferenced](https://github.github.io/openapi/latest/ghe-2.15-deref.yml)
- `GHE 2.16`: [bundled](https://github.github.io/openapi/latest/ghe-2.16.yml), [dereferenced](https://github.github.io/openapi/latest/ghe-2.16-deref.yml)
- `GHE 2.17`: [bundled](https://github.github.io/openapi/latest/ghe-2.17.yml), [dereferenced](https://github.github.io/openapi/latest/ghe-2.17-deref.yml)
- `GHE 2.18`: [bundled](https://github.github.io/openapi/latest/ghe-2.18.yml), [dereferenced](https://github.github.io/openapi/latest/ghe-2.18-deref.yml)

### 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](https://github.com/github/openapi/tree/gh-pages).

## 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](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself), these files make extensive use of [JSON Schema `$ref`s](https://json-schema.org/understanding-json-schema/structuring.html), 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](#usage) below for more details.

If you'd like to contribute to this project, please see [CONTRIBUTING.md](CONTRIBUTING.md)

## Contributors ✨

Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
<!-- prettier-ignore-start -->
<!-- markdownlint-disable -->
<table>
  <tr>
    <td align="center"><a href="https://redoc.ly"><img src="https://avatars0.githubusercontent.com/u/3975738?v=4" width="100px;" alt=""/><br /><sub><b>Roman Hotsiy</b></sub></a><br /><a href="https://github.com/github/openapi/commits?author=RomanHotsiy" title="Code">💻</a> <a href="https://github.com/github/openapi/commits?author=RomanHotsiy" title="Documentation">📖</a> <a href="#ideas-RomanHotsiy" title="Ideas, Planning, & Feedback">🤔</a> <a href="https://github.com/github/openapi/pulls?q=is%3Apr+reviewed-by%3ARomanHotsiy" title="Reviewed Pull Requests">👀</a> <a href="#example-RomanHotsiy" title="Examples">💡</a></td>
    <td align="center"><a href="https://twitter.com/gr2m"><img src="https://avatars3.githubusercontent.com/u/39992?v=4" width="100px;" alt=""/><br /><sub><b>Gregor Martynus</b></sub></a><br /><a href="https://github.com/github/openapi/commits?author=gr2m" title="Code">💻</a> <a href="#content-gr2m" title="Content">🖋</a> <a href="https://github.com/github/openapi/commits?author=gr2m" title="Documentation">📖</a> <a href="#ideas-gr2m" title="Ideas, Planning, & Feedback">🤔</a> <a href="https://github.com/github/openapi/pulls?q=is%3Apr+reviewed-by%3Agr2m" title="Reviewed Pull Requests">👀</a></td>
    <td align="center"><a href="http://zeke.sikelianos.com"><img src="https://avatars1.githubusercontent.com/u/2289?v=4" width="100px;" alt=""/><br /><sub><b>Zeke Sikelianos</b></sub></a><br /><a href="#ideas-zeke" title="Ideas, Planning, & Feedback">🤔</a> <a href="https://github.com/github/openapi/pulls?q=is%3Apr+reviewed-by%3Azeke" title="Reviewed Pull Requests">👀</a></td>
    <td align="center"><a href="https://github.com/sarahs"><img src="https://avatars3.githubusercontent.com/u/821071?v=4" width="100px;" alt=""/><br /><sub><b>Sarah Schneider</b></sub></a><br /><a href="https://github.com/github/openapi/pulls?q=is%3Apr+reviewed-by%3Asarahs" title="Reviewed Pull Requests">👀</a></td>
    <td align="center"><a href="https://productionreadygraphql.com"><img src="https://avatars3.githubusercontent.com/u/1919498?v=4" width="100px;" alt=""/><br /><sub><b>Marc-Andre Giroux</b></sub></a><br /><a href="#ideas-xuorig" title="Ideas, Planning, & Feedback">🤔</a></td>
    <td align="center"><a href="https://www.keithcirkel.co.uk"><img src="https://avatars3.githubusercontent.com/u/118266?v=4" width="100px;" alt=""/><br /><sub><b>Keith Cirkel</b></sub></a><br /><a href="#infra-keithamus" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a></td>
  </tr>
</table>

<!-- markdownlint-enable -->
<!-- prettier-ignore-end -->
<!-- ALL-CONTRIBUTORS-LIST:END -->

This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
