# 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 is a work in progress, owned by the [@github/product-docs-engineering](https://github.com/orgs/github/teams/product-docs-engineering) team. If you have questions, reach out to us in [#docs-engineering](https://github.slack.com/messages/CCHSJFPK9) on Slack.

## Installation

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

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

## Usage

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

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

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