26 lines
1.3 KiB
Markdown
26 lines
1.3 KiB
Markdown
# REST
|
|
|
|
## About this directory
|
|
|
|
* `lib/rest/index.js` is human-editable.
|
|
* `lib/rest/static/*.json` are generated by [scripts](../../script/rest/README.md).
|
|
|
|
## Editable files
|
|
|
|
* `lib/rest/index.js` consumes the static decorated schema files and exports `categories`, `operations`, and `operationsEnabledForGitHubApps` used by the REST middleware contextualizer.
|
|
|
|
## Static files
|
|
|
|
Generated by `script/rest/update-files.js`:
|
|
|
|
* `lib/rest/static/decorated` - files generated from the dereferenced OpenAPI schema with the Markdown descriptions rendered in HTML
|
|
* `lib/rest/static/dereferenced` - **NOTE** These are only generated if you pass the --keep-dereferenced-files option and are not checked into the repository. This option is for debug only.
|
|
|
|
## Rendering docs
|
|
|
|
When the server starts, `middleware/contextualizers/rest.js` accesses the data exported from the static decorated JSON files, fetches the data for the current version and requested path, and adds it to the `context` object. The added property is:
|
|
|
|
* `req.context.currentRestOperations` - all operations with a category matching the current path
|
|
|
|
Markdown files in `content/rest/reference` use Liquid to loop over these context properties. The Liquid calls HTML files in the `includes` directory to do most of the rendering. Writers can add content to the Markdown files alongside the Liquid.
|