@github/openapi

# This project is no longer maintained! The official OpenAPI descriptions for GitHub's REST API are now available at [github.com/github/rest-api-description](https://github.com/github/rest-api-description). Have a nice day! --- --- --- --- --- --- --- # @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. 👋 Here to use the OpenAPI schema? See [Downloads](#downloads) 👋 Here to contribute? See [CONTRIBUTING.md](CONTRIBUTING.md) ## Contents - [What is OpenAPI?](#what-is-openapi) - [Who's using this?](#whos-using-this) - [Projects status](#project-status) - [Downloads](#downloads) - [Usage](#usage) - [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 [docs.github.com/rest/reference](https://docs.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.) ## Project status This project is under active development and is rapidly evolving. To borrow from [Slack's OpenAPI README](https://github.com/slackapi/slack-api-specs): > We use a combination of internal metadata, custom scripting, and old fashioned writing-by-hand to produce these specifications. They don't always tell the whole truth and are subject to author and operator error. They are really useful though. 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. ## Downloads ✋ Before using these OpenAPI definitions, please read the [project status](#project-status). You can download the latest [`api.github.com-deref.json`](https://unpkg.com/browse/@github/openapi@latest/dist/api.github.com-deref.json) from unpkg.com or [view all versions](https://unpkg.com/@github/openapi/dist/) of the schema. If you're using Node.js, you can download and install the [`@github/openapi`](https://npm.im/@github/openapi) package using npm: ```sh npm install @github/openapi ``` ## Usage After installing the npm package, the raw schema files can be required directly: ```js const schema = require('@github/openapi/dist/api.github.com.json') ``` The package also exports a single object called `schemas` that includes referenced and dereferenced variants of the schema for api.github.com and GitHub Enterprise: ```js const { schemas } = require('@github/openapi') // { // 'api.github.com-deref': {...}, // 'api.github.com': {...}, // 'ghe-2.18-deref': {...}, // 'ghe-2.18': {...}, // 'ghe-2.19-deref': {...}, // 'ghe-2.19': {...}, // 'ghe-2.20-deref': {...}, // 'ghe-2.20': {...},, // 'ghe-2.21-deref': {...}, // 'ghe-2.21': {...} // } ``` ## Contributors ✨ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):    <table> <tr> <td align="center"><a href="https://redoc.ly"><img src="https://avatars0.githubusercontent.com/u/3975738?v=4" width="100px;" alt=""/> Roman Hotsiy</a> <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=""/> Gregor Martynus</a> <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=""/> Zeke Sikelianos</a> <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=""/> Sarah Schneider</a> <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=""/> Marc-Andre Giroux</a> <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=""/> Keith Cirkel</a> <a href="#infra-keithamus" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a></td> <td align="center"><a href="https://github.com/rachmari"><img src="https://avatars2.githubusercontent.com/u/9831992?v=4" width="100px;" alt=""/> Rachael Sewell</a> <a href="https://github.com/github/openapi/commits?author=rachmari" title="Documentation">📖</a> <a href="https://github.com/github/openapi/pulls?q=is%3Apr+reviewed-by%3Arachmari" title="Reviewed Pull Requests">👀</a></td> </tr> <tr> <td align="center"><a href="https://chiedojohn.com"><img src="https://avatars2.githubusercontent.com/u/2156688?v=4" width="100px;" alt=""/> Chiedo John</a> <a href="https://github.com/github/openapi/commits?author=chiedo" title="Documentation">📖</a></td> <td align="center"><a href="https://github.com/adamaltman"><img src="https://avatars2.githubusercontent.com/u/1161871?v=4" width="100px;" alt=""/> Adam Altman</a> <a href="https://github.com/github/openapi/commits?author=adamaltman" title="Documentation">📖</a> <a href="https://github.com/github/openapi/pulls?q=is%3Apr+reviewed-by%3Aadamaltman" title="Reviewed Pull Requests">👀</a></td> <td align="center"><a href="http://cleartext.dev"><img src="https://avatars3.githubusercontent.com/u/54248166?v=4" width="100px;" alt=""/> Martin Lopes</a> <a href="https://github.com/github/openapi/commits?author=martin389" title="Documentation">📖</a></td> <td align="center"><a href="https://lucascosti.com"><img src="https://avatars3.githubusercontent.com/u/4434330?v=4" width="100px;" alt=""/> Lucas Costi</a> <a href="https://github.com/github/openapi/commits?author=lucascosti" title="Documentation">📖</a></td> <td align="center"><a href="https://github.com/jmarlena"><img src="https://avatars3.githubusercontent.com/u/6732600?v=4" width="100px;" alt=""/> jmarlena</a> <a href="https://github.com/github/openapi/commits?author=jmarlena" title="Documentation">📖</a></td> </tr> </table>    This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!