# openapi
[![All Contributors](https://img.shields.io/badge/all_contributors-4-orange.svg?style=flat-square)](#contributors)

> OpenAPI schema for GitHub's REST API

This repo contains the official OpenAPI schemas 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.

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

## 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](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)

## 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()
```

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

## 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](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).

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