Skip to content

Commit 8f0093c

Browse files
sarahssarahs
authored
OpenAPI tooling updates (github#16320)
1 parent 6223032 commit 8f0093c

30 files changed

Lines changed: 2339953 additions & 132 deletions

‎.github/actions-scripts/openapi-schema-branch.js‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
#!/usr/bin/env node
2+
3+
const fs = require('fs')
4+
const path = require('path')
5+
const { execSync } = require('child_process')
6+
const semver = require('semver')
7+
8+
/*
9+
* This script performs two checks to prevent shipping development mode OpenAPI schemas:
10+
* - Ensures the `info.version` property is a semantic version.
11+
* In development mode, the `info.version` property is a string
12+
* containing the `github/github` branch name.
13+
* - Ensures the decorated schema matches the dereferenced schema.
14+
* The workflow that calls this script runs `script/rest/update-files.js`
15+
* with the `--decorate-only` switch then checks to see if files changed.
16+
*
17+
*/
18+
19+
// Check that the `info.version` property is a semantic version
20+
const dereferencedDir = path.join(process.cwd(), 'lib/rest/static/dereferenced')
21+
const schemas = fs.readdirSync(dereferencedDir)
22+
schemas.forEach(filename => {
23+
const schema = require(path.join(dereferencedDir, filename))
24+
if (!semver.valid(schema.info.version)) {
25+
console.log(`🚧⚠️ Your branch contains a development mode OpenAPI schema: ${schema.info.version}. This check is a reminder to not 🚢 OpenAPI files in development mode. 🛑`)
26+
process.exit(1)
27+
}
28+
})
29+
30+
// Check that the decorated schema matches the dereferenced schema
31+
const changedFiles = execSync('git diff --name-only HEAD').toString()
32+
33+
if(changedFiles !== '') {
34+
console.log(`These files were changed:\n${changedFiles}`)
35+
console.log(`🚧⚠️ Your decorated and dereferenced schema files don't match. Ensure you're using decorated and dereferenced schemas from the automatically created pull requests by the 'github-openapi-bot' user. For more information, see 'script/rest/README.md'. 🛑`)
36+
process.exit(1)
37+
}
38+
39+
// All checks pass, ready to ship
40+
console.log('All good 👍')
41+
process.exit(0)

‎.github/allowed-actions.js‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,5 +29,6 @@ module.exports = [
2929
'repo-sync/github-sync@3832fe8e2be32372e1b3970bbae8e7079edeec88',
3030
'repo-sync/pull-request@33777245b1aace1a58c87a29c90321aa7a74bd7d',
3131
'rtCamp/action-slack-notify@e17352feaf9aee300bf0ebc1dfbf467d80438815',
32-
'tjenkinson/gh-action-auto-merge-dependency-updates@cee2ac0'
32+
'tjenkinson/gh-action-auto-merge-dependency-updates@cee2ac0',
33+
'EndBug/add-and-commit@9358097a71ad9fb9e2f9624c6098c89193d83575'
3334
]

‎.github/workflows/openapi-decorate.yml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
name: OpenAPI generate decorated schema files
2+
3+
on:
4+
workflow_dispatch:
5+
pull_request:
6+
types: [opened]
7+
8+
jobs:
9+
generate-decorated-files:
10+
if: github.event.pull_request.user.login == 'github-openapi-bot'
11+
runs-on: ubuntu-latest
12+
steps:
13+
- name: Checkout repository code
14+
uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f
15+
16+
- name: Install dependencies
17+
run: npm ci
18+
19+
- name: Decorate the dereferenced OpenAPI schemas
20+
run: script/rest/update-files.js --decorate-only
21+
22+
- name: Check in the decorated files
23+
uses: EndBug/add-and-commit@9358097a71ad9fb9e2f9624c6098c89193d83575
24+
with:
25+
# The arguments for the `git add` command
26+
add: 'lib/rest/static/decorated'
27+
28+
# The message for the commit
29+
message: 'Add decorated OpenAPI schema files'
30+
31+
env:
32+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Leave this line unchanged

‎.github/workflows/openapi-schema-check.yml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
name: OpenAPI dev mode check
2+
3+
on:
4+
workflow_dispatch:
5+
push:
6+
7+
jobs:
8+
check-schema-versions:
9+
runs-on: ubuntu-latest
10+
steps:
11+
- name: Checkout repository code
12+
uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f
13+
14+
- name: Install dependencies
15+
run: npm ci
16+
17+
# Differences between decorated and dereferenced files indicates a problem
18+
- name: Generate decorated files to check that there are no differences
19+
run: script/rest/update-files.js --decorate-only
20+
21+
- name: Check if deref/decorated schemas are dev mode and that they match
22+
run: .github/actions-scripts/openapi-schema-branch.js

‎lib/rest/README.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# REST
2+
3+
## About this directory
4+
5+
* `lib/rest/index.js` is human-editable.
6+
* `lib/rest/static/*.json` are generated by [scripts](../../script/rest/README.md).
7+
8+
## Editable files
9+
10+
* `lib/rest/index.js` consumes the static decorated schema files and exports `categories`, `operations`, and `operationsEnabledForGitHubApps` used by the REST middleware contextualizer.
11+
12+
## Static files
13+
14+
Generated by `script/rest/update-files.js`:
15+
16+
* `lib/rest/static/dereferenced` - dereferenced OpenAPI schema file for each version of GitHub
17+
* `lib/rest/static/decorated` - files generated from the dereferenced OpenAPI schema with the Markdown descriptions rendered in HTML
18+
19+
## Rendering docs
20+
21+
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:
22+
23+
* `req.context.currentRestOperations` - all operations with a category matching the current path
24+
25+
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.

lib/rest.js renamed to lib/rest/index.js

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,15 @@
1+
const fs = require('fs')
2+
const path = require('path')
13
const { chain, get, groupBy } = require('lodash')
2-
const operations = require('@github/rest-api-operations')
3-
const allVersions = require('./all-versions')
4+
const schemasPath = path.join(__dirname, 'static/decorated')
5+
const operations = {}
6+
fs.readdirSync(schemasPath)
7+
.forEach(filename => {
8+
const key = filename.replace('.json', '')
9+
const value = require(path.join(schemasPath, filename))
10+
operations[key] = value
11+
})
12+
const allVersions = require('../all-versions')
413
const allVersionKeys = Object.keys(allVersions)
514

615
let allCategories = []

‎lib/rest/static/decorated/api.github.com.json‎

Lines changed: 86101 additions & 0 deletions
Large diffs are not rendered by default.

0 commit comments

Comments
 (0)