# @github/rest-api-operations

A Node.js module that decorates GitHub OpenAPI schemas for rendering on [docs.github.com](https://docs.github.com/rest/reference).

## What it does

- Generates arrays of [Operation](lib/operation.js) objects from GitHub OpenAPI schemas
- Validates generated operations using a [JSON schema](lib/operation-schema.js)
- Generates code samples for `curl`, [@octokit/core.js](https://github.com/octokit/core.js), and [octokit.rb](https://github.com/octokit/octokit.rb). See [Extensions](extsensions.md).
- Renders operation markdown properties to HTML using [hubdown](https://ghub.io/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](https://ghub.io/github-slugger)
- Adds HTTP status messages to responses using [http-status-code](https://ghub.io/https-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](https://github.com/semantic-release) and a GitHub Actions [workflow](.github/actions/release.yml) 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](https://www.youtube.com/watch?v=rCXq86FOlzQ).

## Installation

```sh
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.

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

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

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