README
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. Have a nice day!
@github/openapi
This project houses the official OpenAPI definitions for GitHub's REST API, 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
👋 Here to contribute? See CONTRIBUTING.md
Contents
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.
Who's using this?
These definitions are used to generate GitHub's REST API reference documentation at docs.github.com/rest/reference.
These definitions will also soon be used to generate the JavaScript and Ruby 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:
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 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.
You can download the latest api.github.com-deref.json from unpkg.com or view all versions of the schema.
If you're using Node.js, you can download and install the @github/openapi package using npm:
npm install @github/openapi
Usage
After installing the npm package, the raw schema files can be required directly:
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:
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):
This project follows the all-contributors specification. Contributions of any kind welcome!