Skip to content

Commit 0506936

Browse files
hectorsectorhectorsector
authored
Add docs for the article API (#54801)
1 parent 5a650b8 commit 0506936

6 files changed

Lines changed: 426 additions & 1 deletion

File tree

‎.github/workflows/article-api-docs.yml‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
name: 'Check article-api docs'
2+
3+
# **What it does**: Makes sure changes to the article api are documented.
4+
# **Why we have it**: So what's documented doesn't fall behind
5+
# **Who does it impact**: Docs engineering, CGS team
6+
7+
on:
8+
workflow_dispatch:
9+
pull_request:
10+
paths:
11+
- 'src/article-api/middleware/article.ts'
12+
- 'src/article-api/middleware/pagelist.ts'
13+
# Self-test
14+
- .github/workflows/article-api-docs.yml
15+
16+
permissions:
17+
contents: read
18+
19+
jobs:
20+
check-content-linter-rules-docs:
21+
runs-on: ${{ fromJSON('["ubuntu-latest", "ubuntu-20.04-xl"]')[github.repository == 'github/docs-internal'] }}
22+
if: github.repository == 'github/docs-internal' || github.repository == 'github/docs'
23+
steps:
24+
- name: Checkout
25+
uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
26+
27+
- uses: ./.github/actions/node-npm-setup
28+
29+
- name: Check that src/article-api/README.md is up-to-date
30+
run: npm run generate-article-api-docs
31+
32+
- name: Fail if it isn't up-to-date
33+
run: |
34+
if [ -n "$(git status --porcelain)" ]; then
35+
git status
36+
git diff
37+
38+
# Some whitespace for the sake of the message below
39+
echo ""
40+
echo ""
41+
42+
echo "src/article-api/README.md is out of date."
43+
echo "Please run 'npm run generate-article-api-docs' and commit the changes."
44+
exit 1;
45+
fi

‎package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,7 @@
5757
"lint-content": "tsx src/content-linter/scripts/lint-content.js",
5858
"lint-translation": "vitest src/content-linter/tests/lint-files.js",
5959
"liquid-markdown-tables": "tsx src/tools/scripts/liquid-markdown-tables/index.ts",
60+
"generate-article-api-docs": "tsx src/article-api/scripts/generate-api-docs.ts",
6061
"generate-code-scanning-query-list": "tsx src/code-scanning/scripts/generate-code-scanning-query-list.ts",
6162
"generate-content-linter-docs": "tsx src/content-linter/scripts/generate-docs.ts",
6263
"move-content": "tsx src/content-render/scripts/move-content.js",

‎src/article-api/README.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,3 +22,128 @@ The `/api/article` endpoints return information about a page by `pathname`.
2222
For internal folks ask in the Docs Engineering slack channel.
2323

2424
For open source folks, please open a discussion in the public repository.
25+
26+
<!-- API reference docs automatically generated, do not edit below this comment -->
27+
## Reference: API endpoints
28+
29+
### GET /api/article/
30+
31+
Get article metadata and content in a single object. Equivalent to calling `/article/meta` concatenated with `/article/body`.
32+
33+
**Parameters**:
34+
- **pathname** (string) - Article path (e.g. '/en/get-started/article-name')
35+
36+
**Returns**: (object) - JSON object with article metadata and content (`meta` and `body` keys)
37+
38+
**Throws**:
39+
- (Error): 403 - If the article body cannot be retrieved. Reason is given in the error message.
40+
- (Error): 400 - If pathname parameter is invalid.
41+
- (Error): 404 - If the path is valid, but the page couldn't be resolved.
42+
43+
**Example**:
44+
```
45+
❯ curl -s "https://docs.github.com/api/article?pathname=/en/get-started/start-your-journey/about-github-and-git"
46+
{
47+
"meta": {
48+
"title": "About GitHub and Git",
49+
"intro": "You can use GitHub and Git to collaborate on work.",
50+
"product": "Get started"
51+
},
52+
"body": "## About GitHub\n\nGitHub is a cloud-based platform where you can store, share, and work together with others to write code.\n\nStoring your code in a \"repository\" on GitHub allows you to:\n\n* **Showcase or share** your work.\n [...]"
53+
}
54+
```
55+
56+
---
57+
58+
### GET /api/article/body
59+
60+
Get the contents of an article's body.
61+
62+
**Parameters**:
63+
- **pathname** (string) - Article path (e.g. '/en/get-started/article-name')
64+
65+
**Returns**: (string) - Article body content in markdown format.
66+
67+
**Throws**:
68+
- (Error): 403 - If the article body cannot be retrieved. Reason is given in the error message.
69+
- (Error): 400 - If pathname parameter is invalid.
70+
- (Error): 404 - If the path is valid, but the page couldn't be resolved.
71+
72+
**Example**:
73+
```
74+
❯ curl -s https://docs.github.com/api/article/body\?pathname=/en/get-started/start-your-journey/about-github-and-git
75+
## About GitHub
76+
77+
GitHub is a cloud-based platform where you can store, share, and work together with others to write code.
78+
79+
Storing your code in a "repository" on GitHub allows you to:
80+
[...]
81+
```
82+
83+
---
84+
85+
### GET /api/article/meta
86+
87+
Get metadata about an article.
88+
89+
**Parameters**:
90+
- **pathname** (string) - Article path (e.g. '/en/get-started/article-name')
91+
92+
**Returns**: (object) - JSON object containing article metadata with title, intro, and product information.
93+
94+
**Throws**:
95+
- (Error): 400 - If pathname parameter is invalid.
96+
- (Error): 404 - If the path is valid, but the page couldn't be resolved.
97+
98+
**Example**:
99+
```
100+
❯ curl -s "https://docs.github.com/api/article/meta?pathname=/en/get-started/start-your-journey/about-github-and-git"
101+
{
102+
"title": "About GitHub and Git",
103+
"intro": "You can use GitHub and Git to collaborate on work.",
104+
"product": "Get started",
105+
"breadcrumbs": [
106+
{
107+
"href": "/en/get-started",
108+
"title": "Get started"
109+
},
110+
{
111+
"href": "/en/get-started/start-your-journey",
112+
"title": "Start your journey"
113+
},
114+
{
115+
"href": "/en/get-started/start-your-journey/about-github-and-git",
116+
"title": "About GitHub and Git"
117+
}
118+
]
119+
}
120+
```
121+
122+
---
123+
124+
### GET /api/pagelist/:lang/:productVersion
125+
126+
A list of pages available for a fully qualified path containing the target language and product version.
127+
128+
**Parameters**:
129+
- **lang** (string) - Path parameter for language code (e.g. 'en')
130+
- **productVersion** (string) - Path parameter for product version (e.g. 'free-pro-team@latest')
131+
132+
**Returns**: (string) - List of paths matching the language and version
133+
134+
**Throws**:
135+
- (Error): 400 - If language or version parameters are invalid. Reason is given in the error message.
136+
137+
**Example**:
138+
```
139+
❯ curl -s https://docs.github.com/api/pagelist/en/free-pro-team@latest
140+
/en
141+
/en/search
142+
/en/get-started
143+
/en/get-started/start-your-journey
144+
/en/get-started/start-your-journey/about-github-and-git
145+
[...]
146+
```
147+
148+
---
149+

‎src/article-api/middleware/article.ts‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,25 @@ const router = express.Router()
2020
// - pathValidationMiddleware ensures the path is properly structured and handles errors when it's not
2121
// - pageValidationMiddleware fetches the page from the pagelist, returns 404 to the user if not found
2222

23+
/**
24+
* Get article metadata and content in a single object. Equivalent to calling `/article/meta` concatenated with `/article/body`.
25+
* @route GET /api/article
26+
* @param {string} pathname - Article path (e.g. '/en/get-started/article-name')
27+
* @returns {object} JSON object with article metadata and content (`meta` and `body` keys)
28+
* @throws {Error} 403 - If the article body cannot be retrieved. Reason is given in the error message.
29+
* @throws {Error} 400 - If pathname parameter is invalid.
30+
* @throws {Error} 404 - If the path is valid, but the page couldn't be resolved.
31+
* @example
32+
* ❯ curl -s "https://docs.github.com/api/article?pathname=/en/get-started/start-your-journey/about-github-and-git"
33+
* {
34+
* "meta": {
35+
* "title": "About GitHub and Git",
36+
* "intro": "You can use GitHub and Git to collaborate on work.",
37+
* "product": "Get started"
38+
* },
39+
* "body": "## About GitHub\n\nGitHub is a cloud-based platform where you can store, share, and work together with others to write code.\n\nStoring your code in a \"repository\" on GitHub allows you to:\n\n* **Showcase or share** your work.\n [...]"
40+
* }
41+
*/
2342
router.get(
2443
'/',
2544
pathValidationMiddleware as RequestHandler,
@@ -43,6 +62,23 @@ router.get(
4362
}),
4463
)
4564

65+
/**
66+
* Get the contents of an article's body.
67+
* @route GET /api/article/body
68+
* @param {string} pathname - Article path (e.g. '/en/get-started/article-name')
69+
* @returns {string} Article body content in markdown format.
70+
* @throws {Error} 403 - If the article body cannot be retrieved. Reason is given in the error message.
71+
* @throws {Error} 400 - If pathname parameter is invalid.
72+
* @throws {Error} 404 - If the path is valid, but the page couldn't be resolved.
73+
* @example
74+
* ❯ curl -s https://docs.github.com/api/article/body\?pathname=/en/get-started/start-your-journey/about-github-and-git
75+
* ## About GitHub
76+
*
77+
* GitHub is a cloud-based platform where you can store, share, and work together with others to write code.
78+
*
79+
* Storing your code in a "repository" on GitHub allows you to:
80+
* [...]
81+
*/
4682
router.get(
4783
'/body',
4884
pathValidationMiddleware as RequestHandler,
@@ -62,6 +98,35 @@ router.get(
6298
}),
6399
)
64100

101+
/**
102+
* Get metadata about an article.
103+
* @route GET /api/article/meta
104+
* @param {string} pathname - Article path (e.g. '/en/get-started/article-name')
105+
* @returns {object} JSON object containing article metadata with title, intro, and product information.
106+
* @throws {Error} 400 - If pathname parameter is invalid.
107+
* @throws {Error} 404 - If the path is valid, but the page couldn't be resolved.
108+
* @example
109+
* ❯ curl -s "https://docs.github.com/api/article/meta?pathname=/en/get-started/start-your-journey/about-github-and-git"
110+
* {
111+
* "title": "About GitHub and Git",
112+
* "intro": "You can use GitHub and Git to collaborate on work.",
113+
* "product": "Get started",
114+
* "breadcrumbs": [
115+
* {
116+
* "href": "/en/get-started",
117+
* "title": "Get started"
118+
* },
119+
* {
120+
* "href": "/en/get-started/start-your-journey",
121+
* "title": "Start your journey"
122+
* },
123+
* {
124+
* "href": "/en/get-started/start-your-journey/about-github-and-git",
125+
* "title": "About GitHub and Git"
126+
* }
127+
* ]
128+
* }
129+
*/
65130
router.get(
66131
'/meta',
67132
pathValidationMiddleware as RequestHandler,

‎src/article-api/middleware/pagelist.ts‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,22 @@ router.get(
4444
}),
4545
)
4646

47-
// for a fully qualified path with language and product version, we'll serve up the pagelist
47+
/**
48+
* A list of pages available for a fully qualified path containing the target language and product version.
49+
* @route GET /api/pagelist
50+
* @param {string} lang - Path parameter for language code (e.g. 'en')
51+
* @param {string} productVersion - Path parameter for product version (e.g. 'free-pro-team@latest')
52+
* @returns {string} List of paths matching the language and version
53+
* @throws {Error} 400 - If language or version parameters are invalid. Reason is given in the error message.
54+
* @example
55+
* ❯ curl -s https://docs.github.com/api/pagelist/en/free-pro-team@latest
56+
* /en
57+
* /en/search
58+
* /en/get-started
59+
* /en/get-started/start-your-journey
60+
* /en/get-started/start-your-journey/about-github-and-git
61+
* [...]
62+
*/
4863
router.get(
4964
'/:lang/:productVersion',
5065
pagelistValidationMiddleware as RequestHandler,

0 commit comments

Comments
 (0)