@github/rest-api-operations

A Node.js module that decorates GitHub's OpenAPI schemas for rendering on docs.github.com

Usage no npm install needed!

<script type="module">
  import githubRestApiOperations from 'https://cdn.skypack.dev/@github/rest-api-operations';
</script>

README

This project is no longer maintained!

The decorated OpenAPI files are no longer generated from this repository. The code in this repository has been migrated over to github/docs-internal and a workflow automatically runs a script to decorate dereferenced OpenAPI schema files when PRs are opened in the github/docs-internal repo by github-openapi-bot.

@github/rest-api-operations

A Node.js module that decorates GitHub OpenAPI schemas for rendering on docs.github.com.

What it does

  • Generates arrays of Operation objects from GitHub OpenAPI schemas
  • Validates generated operations using a JSON schema
  • Generates code samples for curl, @octokit/core.js, and octokit.rb. See Extensions.
  • Renders operation markdown properties to HTML using hubdown:
    • descriptions
    • code samples
    • response payloads
    • parameter descriptions
    • body paramater descriptions
    • preview notices
  • Adds slug properties to each operation for use as unique DOM ids using github-slugger
  • Adds HTTP status messages to responses using http-status-code
  • Derives category and subcategory to support legacy /v3/{category}/{subcategory} URLs
  • Matches internal nomenclature for GitHub product variants, e.g. dotcom and 2.20

Publishing process

This project uses semantic-release and a GitHub Actions workflow to automatically publish a new version of the npm package whenever pull requests are merged to the default branch. To enable this, we give our pull request titles semantic prefixes like fix: and feat: . To learn more about semantic-release and semantic commit messages, watch this YouTube video.

Installation

npm install @github/rest-api-operations

Usage

The npm module exports a single property schemas which is an object containing multiple versions of the GitHub REST API schema for api.github.com and all currently supported versions of GitHub Enterprise Server.

const { schemas } = require('@github/rest-api-operations')

console.log(Object.keys(schemas))
// [
//   'api.github.com',
//   'ghes-2.17',
//   'ghes-2.18',
//   'ghes-2.19',
//   'ghes-2.20'
// ]

console.log(schemas['ghes-2.20'])
// [
//   { Operation },
//   { Operation },
//   { Operation },
//   ...
// ]

Previewing changes locally

Sometimes it's helpful to preview changes you've made to this module on your local checkout of the GitHub Docs website. Assuming you have the two repositories checked out in the same parent directory, run the following:

cd ~/your-checkout-of/github/docs-internal
npm link ../rest-api-operations
cd ../rest-api-operations
npm run watch

This creates a symlink between the two projects and starts a watcher process that runs the @github/rest-api-operations build script whenever you make changes to its source files. These changes should be visible on your local development server.

When you're done previewing changes, remove the symlink:

cd ~/your-checkout-of/github/docs-internal
npm unlink ../rest-api-operations