docs(website): document the OpenAPI path-key normalization
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>
This commit is contained in:
@@ -278,6 +278,11 @@ it churns whenever a description is reworded — it documents *intent*. The mani
|
||||
derived and records *reality*, which is why it, not Swagger, is the thing PR checks freeze
|
||||
(`npm run routes:manifest -- --check`).
|
||||
|
||||
Both artifacts are emitted with **sorted** keys, so a diff in either is proportional to the change
|
||||
rather than to how the routers happen to be traversed. `swagger.js` additionally strips trailing
|
||||
slashes from generated path keys — see *Regenerating the spec* in the website README for why the
|
||||
domain split makes that necessary.
|
||||
|
||||
Scope: the manifest keeps `/api/**` and `/.well-known/**` from the public app plus everything on the
|
||||
internal listener. The SPA catch-all, `/uploads` and `/brand` are filesystem-conditional static
|
||||
mounts — not API contract, and including them would make the output depend on whether CI had built
|
||||
|
||||
Reference in New Issue
Block a user