Skip to content

Commit 9053e0e

Browse files
committed
Add versioned bundle builder with x-github-api-versions support
This adds a Node.js script to build OpenAPI bundles that include the API version number using the x-github-api-versions custom extension. Changes: - Add scripts/build-versioned-bundles.js for generating versioned bundles - Update package.json with build scripts and js-yaml dependency - Document x-github-api-versions extension in extensions.md - Add output/ to .gitignore Usage: npm run build # Build all releases npm run build:api.github.com # Build only api.github.com node scripts/build-versioned-bundles.js --versions 2022-11-28
1 parent 04fd6c5 commit 9053e0e

4 files changed

Lines changed: 395 additions & 3 deletions

File tree

.gitignore

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,2 @@
1-
node_modules/
1+
node_modules/
2+
output/

extensions.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,30 @@
22

33
This document describes the [OpenAPI extensions](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#specification-extensions) used in GitHub's REST API OpenAPI descriptions.
44

5+
## `x-github-api-versions`
6+
7+
### Purpose
8+
9+
To specify the API versions supported by this OpenAPI description. GitHub's REST API uses calendar-based versioning (e.g., `2022-11-28`). Clients can use the `X-GitHub-Api-Version` header to request a specific version.
10+
11+
### Usage
12+
13+
This applies to the [Info Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#infoObject).
14+
15+
The value should be an array of strings representing supported API version dates in `YYYY-MM-DD` format, sorted in descending order (newest first).
16+
17+
#### Example usage
18+
19+
```yml
20+
info:
21+
title: GitHub v3 REST API
22+
version: 1.1.4
23+
x-github-api-versions:
24+
- "2022-11-28"
25+
```
26+
27+
For more information about API versioning, see the [GitHub REST API documentation](https://docs.github.com/rest/about-the-rest-api/api-versions).
28+
529
## `x-displayName`
630

731
### Purpose

package.json

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,13 +7,19 @@
77
},
88
"license": "MIT",
99
"scripts": {
10-
"lint": "eslint descriptions/**/*.json --ext .json"
10+
"lint": "eslint descriptions/**/*.json --ext .json",
11+
"build": "node scripts/build-versioned-bundles.js",
12+
"build:versioned": "node scripts/build-versioned-bundles.js --output output/versioned",
13+
"build:api.github.com": "node scripts/build-versioned-bundles.js --releases api.github.com",
14+
"build:ghec": "node scripts/build-versioned-bundles.js --releases ghec",
15+
"build:ghes": "node scripts/build-versioned-bundles.js --releases $(ls descriptions | grep ghes | tr '\\n' ',')"
1116
},
1217
"eslintConfig": {
1318
"extends": ["plugin:json/recommended"]
1419
},
1520
"devDependencies": {
1621
"eslint": "^8.13.0",
17-
"eslint-plugin-json": "^3.1.0"
22+
"eslint-plugin-json": "^3.1.0",
23+
"js-yaml": "^4.1.0"
1824
}
1925
}

0 commit comments

Comments
 (0)