GitHub has an official OpenAPI Description now
machine-readable, always up-to-date GitHub REST API route specifications
- The de-referenced OpenAPI documents are uploaded as attachments to each release
Or install from package managers
Example operation
{
"summary": "Lock an issue",
"description": "Users with push access can lock an issue or pull request's conversation.\n\nNote that, if you choose not to pass any parameters, you'll need to set `Content-Length` to zero when calling out to this endpoint. For more information, see \"[HTTP verbs](https://developer.github.com/v3/#http-verbs).\"",
"operationId": "issues-lock",
"tags": ["issues"],
"externalDocs": {
"description": "API method documentation",
"url": "https://developer.github.com/v3/issues/#lock-an-issue"
},
"parameters": [
{
"name": "accept",
"description": "Setting to `application/vnd.github.v3+json` is recommended",
"in": "header",
"schema": {
"type": "string",
"default": "application/vnd.github.v3+json"
}
},
{
"name": "owner",
"in": "path",
"schema": {
"type": "string"
},
"required": true,
"description": "owner parameter"
},
{
"name": "repo",
"in": "path",
"schema": {
"type": "string"
},
"required": true,
"description": "repo parameter"
},
{
"name": "issue_number",
"in": "path",
"schema": {
"type": "integer"
},
"required": true,
"description": "issue_number parameter"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"lock_reason": {
"description": "The reason for locking the issue or pull request conversation. Lock will fail if you don't use one of these reasons: \n\\* `off-topic` \n\\* `too heated` \n\\* `resolved` \n\\* `spam`",
"type": "string",
"enum": ["off-topic", "too heated", "resolved", "spam"]
}
}
}
}
}
},
"responses": {
"204": {
"description": "Empty response"
}
},
"x-code-samples": [
{
"lang": "Shell",
"source": "curl \\\n -XPUT \\\n -H\"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/repos/octocat/:repo/issues/:issue_number/lock"
},
{
"lang": "JS",
"source": "octokit.issues.get({\n owner: 'octocat',\n repo: 'hello-world',\n issue_number: 1\n})"
}
],
"x-github": {
"legacy": false,
"enabledForApps": true,
"githubCloudOnly": false
},
"x-changes": [
{
"type": "parameter",
"date": "2019-04-10",
"note": "\"number\" parameter renamed to \"issue_number\"",
"meta": {
"before": "number",
"after": "issue_number"
}
}
]
}Both endpoints or parameters may be deprecated. The date timestamp can be used to determine how long an Octokit library wants to support the endpoint / parameter. Deprecation information is located in the x-changes array of an operation.
Example for a deprecated parameter
{
"type": "parameter",
"date": "2019-04-10",
"note": "\"number\" parameter renamed to \"issue_number\"",
"meta": {
"before": "number",
"after": "issue_number"
}
}Deprecated endpoints have a type of "idName"
{
"type": "idName",
"date": "2019-03-05",
"note": "\"List all licenses\" renamed to \"List commonly used licenses\"",
"meta": {
"before": {
"idName": "list"
},
"after": {
"idName": "list-commonly-used"
}
}
}const ROUTES = require("@octokit/routes");
// ROUTES has "api.github.com" key and one "ghe-*" key for each supported GHE version
// The value of each key is the full OpenAPI specification for the respective versionThis package updates itself using a daily cronjob running on Travis. All openapi/*.json files are generated by bin/octokit-rest-routes.js.
node bin/octokit-rest-routes.js updateRun node bin/octokit-rest-routes.js --usage for more instructions.
The update script is scraping GitHub’s REST API documentation pages and extracts the meta information using cheerio and a ton of regular expressions :)
For simpler local testing and tracking of changes, all loaded pages are cached in the cache/ folder. To only run the code generating the OpenAPI files without updating the cache, add the --cached option.
node bin/octokit-rest-routes.js update --cachedTo update the enterprise routes for all versions, you have to set the --ghe option.
node bin/octokit-rest-routes.js update --gheYou can optionally pass a version number
node bin/octokit-rest-routes.js update --ghe 2.20- Index page cached in
cache/api.github.com/v3/index.html - Result cached in
cache/api.github.com/pages.json
Opens https://developer.github.com/v3/, find all documentation page URLs in the side bar navigation.
- Documentation pages cached in
cache/v3/*/index.html, e.g.cache/api.github.com/v3/repos/index.html - Documentation sub pages cached in
cache/v3/*/*/index.html, e.g.cache/api.github.com/v3/repos/branches/index.html - All sections found on pages are cached next to the
index.htmlfiles, e.g.cache/api.github.com/v3/repos/sections.json - HTML of sections are stored next to the
index.htmlfiles, e.g.cache/api.github.com/v3/repos/create.html
Loads HTML of each documentation page, finds sections in page.
- Some sections don’t have endpoints, such as Notifications Reasons
- Some sections have multiple endpoints, see #3
Loads HTML of documentation page section. Turns it into openapi/*.json files. In some cases the HTML cannot be turned into an endpoint using the implemented patterns. For these cases custom overrides are defined.
- octokit/graphql-schema – GitHub’s GraphQL Schema with validation
- octokit/webhooks – GitHub Webhooks specifications