Skip to content

Commit c6ad886

Browse files
scriptcodedscriptcoded
committed
feat: better enum structure and docs
1 parent cc73925 commit c6ad886

File tree

16 files changed

+325
-92
lines changed

16 files changed

+325
-92
lines changed

‎.github/workflows/publish-pages.yml‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
name: Publish Documentation to GitHub Pages
2+
3+
on:
4+
push:
5+
6+
jobs:
7+
build:
8+
runs-on: ubuntu-latest
9+
steps:
10+
- uses: actions/checkout@v4
11+
12+
- uses: pnpm/action-setup@v4
13+
14+
- run: pnpm install
15+
16+
- name: Generate OpenAPI spec
17+
run: pnpm run gen:docs
18+
19+
- name: Upload static files as artifact
20+
id: deployment
21+
uses: actions/upload-pages-artifact@v3
22+
with:
23+
path: docs-out
24+
25+
deploy:
26+
needs: build
27+
28+
permissions:
29+
pages: write
30+
id-token: write
31+
32+
environment:
33+
name: github-pages
34+
url: ${{ steps.deployment.outputs.page_url }}
35+
36+
runs-on: ubuntu-latest
37+
steps:
38+
- name: Deploy to GitHub Pages
39+
id: deployment
40+
uses: actions/deploy-pages@v4
41+
42+

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,3 +26,5 @@ lerna-debug.log*
2626

2727
# misc
2828
.DS_Store
29+
30+
docs-out

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99

1010
This server acts as a middleman between applications and Scoutnet. It:
1111
- Reformats responses from Scoutnet to make them easier to work with. For
12-
example, it makes sections look like real groups.
12+
example, it makes HUB sections appear as real groups.
1313
- Provides an OpenAPI document on `/openapi` for better type safety.
1414
- Provides human-readable API documentation on `/docs`.
1515
- Caches responses to easen the burden on Scoutnet.

‎package.json‎

Lines changed: 29 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,30 @@
11
{
2-
"name": "scoutnet-cache",
3-
"type": "module",
4-
"license": "MIT",
5-
"scripts": {
6-
"dev": "node --env-file .env --watch src/index.ts",
7-
"start": "node --env-file .env src/index.ts"
8-
},
9-
"dependencies": {
10-
"@hono/arktype-validator": "^2.0.1",
11-
"@hono/node-server": "^1.18.2",
12-
"@scalar/hono-api-reference": "^0.9.13",
13-
"@scouterna/scoutnet": "^0.3.13",
14-
"arktype": "^2.1.20",
15-
"hono": "^4.9.1",
16-
"hono-openapi": "^0.4.8"
17-
},
18-
"devDependencies": {
19-
"@biomejs/biome": "2.2.0",
20-
"@types/node": "^24.2.1",
21-
"typescript": "^5.9.2"
22-
}
23-
}
2+
"name": "scoutnet-cache",
3+
"type": "module",
4+
"license": "MIT",
5+
"engines": {
6+
"pnpm": ">=10"
7+
},
8+
"scripts": {
9+
"dev": "node --env-file .env --watch src/index.ts",
10+
"start": "node --env-file .env src/index.ts",
11+
"gen:docs": "pnpm run gen:openapi && npm run gen:scalar",
12+
"gen:openapi": "node scripts/generateOpenApiSpec.ts",
13+
"gen:scalar": "node scripts/generateScalarDocs.ts"
14+
},
15+
"dependencies": {
16+
"@hono/arktype-validator": "^2.0.1",
17+
"@hono/node-server": "^1.18.2",
18+
"@scalar/core": "^0.3.11",
19+
"@scalar/hono-api-reference": "^0.9.13",
20+
"@scouterna/scoutnet": "^0.3.13",
21+
"arktype": "^2.1.20",
22+
"hono": "^4.9.1",
23+
"hono-openapi": "^0.4.8"
24+
},
25+
"devDependencies": {
26+
"@biomejs/biome": "2.2.0",
27+
"@types/node": "^24.2.1",
28+
"typescript": "^5.9.2"
29+
}
30+
}

‎pages-out/index.html‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
<!doctype html>
2+
<html>
3+
<head>
4+
<title>Scalar API Reference</title>
5+
<meta charset="utf-8" />
6+
<meta
7+
name="viewport"
8+
content="width=device-width, initial-scale=1" />
9+
</head>
10+
<body>
11+
<div id="app"></div>
12+
<!-- Load the Script -->
13+
<script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
14+
15+
<!-- Initialize the Scalar API Reference -->
16+
<script type="text/javascript">
17+
Scalar.createApiReference('#app', {
18+
"url": "./openapi.json"})
19+
</script>
20+
</body>
21+
</html>

‎pages-out/openapi.json‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
{
2+
"openapi": "3.1.0",
3+
"info": {
4+
"title": "Hono Documentation",
5+
"description": "Development documentation",
6+
"version": "0.0.0"
7+
},
8+
"paths": {
9+
"/groups": {
10+
"get": {
11+
"responses": {
12+
"200": {
13+
"description": "List of groups",
14+
"content": {
15+
"application/json": {
16+
"schema": {
17+
"type": "object",
18+
"properties": {
19+
"groups": {
20+
"type": "array",
21+
"items": {
22+
"type": "object",
23+
"properties": {
24+
"belongsToGroup": {
25+
"anyOf": [
26+
{
27+
"type": "string",
28+
"nullable": true
29+
}
30+
]
31+
},
32+
"id": {
33+
"type": "string"
34+
},
35+
"name": {
36+
"anyOf": [
37+
{
38+
"type": "string",
39+
"nullable": true
40+
}
41+
]
42+
},
43+
"troops": {
44+
"type": "array",
45+
"items": {
46+
"type": "object",
47+
"properties": {
48+
"id": {
49+
"type": "string"
50+
},
51+
"name": {
52+
"type": "string"
53+
},
54+
"type": {
55+
"type": "string"
56+
}
57+
},
58+
"required": [
59+
"id",
60+
"name",
61+
"type"
62+
],
63+
"additionalProperties": false
64+
}
65+
},
66+
"types": {
67+
"type": "array",
68+
"items": {
69+
"type": "string"
70+
}
71+
}
72+
},
73+
"required": [
74+
"belongsToGroup",
75+
"id",
76+
"name",
77+
"troops",
78+
"types"
79+
],
80+
"additionalProperties": false
81+
}
82+
},
83+
"lastFetchedAt": {
84+
"type": "string"
85+
},
86+
"nextFetchAt": {
87+
"type": "string"
88+
}
89+
},
90+
"required": [
91+
"groups",
92+
"lastFetchedAt",
93+
"nextFetchAt"
94+
],
95+
"additionalProperties": false
96+
}
97+
}
98+
}
99+
}
100+
},
101+
"operationId": "getGroups",
102+
"parameters": [],
103+
"description": "Get all groups from cache. If the cache is empty, it will fetch the groups from the Scoutnet API."
104+
}
105+
},
106+
"/groups/refresh": {
107+
"post": {
108+
"responses": {
109+
"204": {
110+
"description": "Groups cache refreshed successfully"
111+
}
112+
},
113+
"operationId": "postGroupsRefresh",
114+
"parameters": [],
115+
"description": "Force refresh the groups cache by fetching from the Scoutnet API."
116+
}
117+
}
118+
},
119+
"components": {
120+
"schemas": {}
121+
}
122+
}

‎pnpm-lock.yaml‎

Lines changed: 3 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎scripts/generateOpenApiSpec.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
import fs, { mkdir } from 'node:fs/promises';
2+
import { generateSpecs } from 'hono-openapi';
3+
import app from '../src/app.ts';
4+
5+
const spec = await generateSpecs(app);
6+
7+
await mkdir('docs-out', { recursive: true });
8+
await fs.writeFile('docs-out/openapi.json', JSON.stringify(spec, null, 2));

‎scripts/generateScalarDocs.ts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
import { mkdir, writeFile } from 'node:fs/promises';
2+
import { getHtmlDocument } from '@scalar/core/libs/html-rendering';
3+
4+
const doc = getHtmlDocument({
5+
url: './openapi.json',
6+
});
7+
8+
await mkdir('docs-out', { recursive: true });
9+
await writeFile('docs-out/index.html', doc);

‎src/app.ts‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,11 @@
11
import './arktypeConfig.ts';
22

33
import { Scalar } from '@scalar/hono-api-reference';
4+
45
import { Hono } from 'hono';
56
import { openAPISpecs } from 'hono-openapi';
67
import groups from './resources/groups/routes.ts';
78

8-
// Import config to ensure environment variables are set
9-
import './config.ts';
10-
119
const app = new Hono();
1210

1311
app
@@ -38,7 +36,7 @@ app
3836
}),
3937
);
4038

41-
const routes = app.route('/groups', groups);
39+
export const routes = app.route('/groups', groups);
4240

4341
export default app;
4442
export type AppType = typeof routes;

0 commit comments

Comments
 (0)