docs(website): document the OpenAPI path-key normalization #52

wtclaude · 2026-07-27T20:51:18Z

wtclaude commented

2026-07-27 20:51:18 +00:00

What & why

Documentation half of RunicGateway/website#101 (build(swagger): normalize and sort generated OpenAPI path keys), which post-processes swagger-autogen's output ahead of the admin router domain split
(API_V2_PLAN.md § Phase 2).

website-README.md § Regenerating the spec — why trailing slashes are stripped from generated
path keys (a capability router mounted at /users declaring router.get('/') would otherwise
document /api/v1/admin/users/, a URL no client calls, while dropping the one they all do), and
why path keys are sorted.
BACKEND_DESIGN.md § generated artifacts — note that both the route manifest and the spec are
emitted with sorted keys, so a diff in either is proportional to the change rather than to router
traversal order.

How it was tested

Markdown only. Cross-checked against the code landing in website#101.

Checklist

I have read CONTRIBUTING.md.
The change builds and existing tests/checks pass locally.
I have added or updated tests/docs where it makes sense.
My commits are reasonably scoped with clear messages.

AI-assisted contributions (required)

No AI tools were used to produce this contribution.
AI tools were used. Tool(s): Claude Code (Opus 5). I have reviewed and understand
every change, and take responsibility for it. AI-authored commits are
marked with a Co-Authored-By / Assisted-By trailer.

License

I agree that my contribution is licensed under this project's license
(GNU GPL v3.0 or later), and I have the right to contribute it.

## What & why Documentation half of RunicGateway/website#101 (`build(swagger): normalize and sort generated OpenAPI path keys`), which post-processes swagger-autogen's output ahead of the admin router domain split (`API_V2_PLAN.md` § Phase 2). - **`website-README.md` § Regenerating the spec** — why trailing slashes are stripped from generated path keys (a capability router mounted at `/users` declaring `router.get('/')` would otherwise document `/api/v1/admin/users/`, a URL no client calls, while dropping the one they all do), and why path keys are sorted. - **`BACKEND_DESIGN.md` § generated artifacts** — note that both the route manifest and the spec are emitted with sorted keys, so a diff in either is proportional to the change rather than to router traversal order. ## How it was tested Markdown only. Cross-checked against the code landing in website#101. ## Checklist - [x] I have read [CONTRIBUTING.md](CONTRIBUTING.md). - [x] The change builds and existing tests/checks pass locally. - [x] I have added or updated tests/docs where it makes sense. - [x] My commits are reasonably scoped with clear messages. ## AI-assisted contributions (required) - [ ] No AI tools were used to produce this contribution. - [x] AI tools were used. Tool(s): `Claude Code (Opus 5)`. I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a `Co-Authored-By` / `Assisted-By` trailer. ## License - [x] I agree that my contribution is licensed under this project's license (**GNU GPL v3.0 or later**), and I have the right to contribute it.

wtclaude added 1 commit 2026-07-27 20:51:20 +00:00

docs(website): document the OpenAPI path-key normalization 31c91fb307

Matches website PR "build(swagger): normalize and sort generated OpenAPI path
keys", which post-processes swagger-autogen's output ahead of the admin router
domain split (API_V2_PLAN.md § Phase 2).

- website-README.md § Regenerating the spec: why trailing slashes are stripped
  (a capability router mounted at /users declaring router.get('/') would document
  /api/v1/admin/users/, a URL no client calls) and why path keys are sorted.
- BACKEND_DESIGN.md § generated artifacts: note that both the route manifest and
  the spec are emitted sorted, so a diff in either is proportional to the change.

Co-Authored-By: Claude <noreply@anthropic.com>

whitlocktech approved these changes 2026-07-27 20:52:05 +00:00

whitlocktech merged commit 6cea1c24c4 into main

2026-07-27 20:52:11 +00:00

whitlocktech referenced this issue from a commit

2026-07-27 20:52:12 +00:00

Merge pull request 'docs(website): document the OpenAPI path-key normalization' (#52) from docs/swagger-normalize-paths into main

whitlocktech deleted branch docs/swagger-normalize-paths

2026-07-27 20:52:13 +00:00

wtclaude referenced this pull request

2026-07-27 20:57:50 +00:00

docs(website): record split PR 1 — admin users, account, invites, auth providers #53

Sign in to join this conversation.