Add Swagger/OpenAPI API docs (swagger-ui + swagger-autogen) #27

wtclaude · 2026-07-03T20:29:10Z

wtclaude commented

2026-07-03 20:29:10 +00:00

Summary

Adds interactive OpenAPI 3.0 / Swagger documentation for the entire REST API, generated directly from the route definitions so it stays in lock-step with the code.

swagger-autogen walks the Express mount chain from src/app.js and emits a fully-qualified spec (/api/v1/...).
swagger-ui-express serves it as browsable, try-it-out docs.
The generated spec is committed, so docs work with no build step; the generator dependency is dev-only and not needed at runtime.

What you get

URL	What
`/api/docs`	Interactive Swagger UI (Authorize + try-it-out)
`/api/docs.json`	Raw OpenAPI 3.0 spec

Coverage: 51 paths / 64 operations, every one tagged, summarized, and documented with parameters, request body, security requirement, and the response codes it actually returns.

Changes

Dependencies (server/package.json)

swagger-ui-express — runtime (ships in the Docker image via --omit=dev)
swagger-autogen — dev-only
New script: npm run swagger

Generator — server/swagger/swagger.js

API metadata, servers, 14 tag groups (Auth, Auth · Mobile, Auth · SSO, Public, and the Admin groups).
Two security schemes: cookieAuth (the uomm_token session cookie) and bearerAuth (mobile access-token JWT).
28 reusable component schemas for request/response bodies.

Per-endpoint annotations — #swagger.* comments added next to every route (auth, mobile, sso, public, admin, plus /api/health). Response codes were taken from the controllers, not guessed: 400 validation, 401/403 auth, 404, 409 conflicts, 429 rate-limits, 302 SSO redirects, 502 mail failure, and multipart for image uploads.

Wiring — server/src/app.js serves /api/docs and /api/docs.json, guarded so a missing spec logs a warning and disables docs instead of crashing.

Docs — README.md gains an "API documentation (Swagger)" section (URLs, how to Authorize in the UI, regeneration command) plus tech-stack and project-structure entries.

Regenerating the spec

After adding or changing a route:

cd server
npm run swagger        # -> server/swagger/swagger-output.json

Verification

Generator run: 51 paths / 64 operations, all with tags + summaries + responses, 0 problems; the docs endpoints themselves are excluded from the spec.
Booted the app and hit the endpoints: /api/docs.json -> 200 (OpenAPI 3.0.0), /api/docs/ -> 200 (UI renders), /api/health -> 200.
Existing test suite: 83/83 pass. All edited files pass node -c.

Reviewer note

Response codes reflect what the handlers actually return. The request/response body shapes in the component schemas are reconstructed from the validators and controllers — worth a glance in the UI to confirm field names match the DB columns exactly before merging.

🤖 Generated with Claude Code

## Summary Adds interactive **OpenAPI 3.0 / Swagger** documentation for the entire REST API, generated directly from the route definitions so it stays in lock-step with the code. - **`swagger-autogen`** walks the Express mount chain from `src/app.js` and emits a fully-qualified spec (`/api/v1/...`). - **`swagger-ui-express`** serves it as browsable, try-it-out docs. - The generated spec is committed, so docs work with **no build step**; the generator dependency is dev-only and not needed at runtime. ## What you get | URL | What | |---|---| | `/api/docs` | Interactive Swagger UI (Authorize + try-it-out) | | `/api/docs.json` | Raw OpenAPI 3.0 spec | Coverage: **51 paths / 64 operations**, every one tagged, summarized, and documented with parameters, request body, security requirement, and the response codes it actually returns. ## Changes **Dependencies** (`server/package.json`) - `swagger-ui-express` — runtime (ships in the Docker image via `--omit=dev`) - `swagger-autogen` — dev-only - New script: `npm run swagger` **Generator** — `server/swagger/swagger.js` - API metadata, servers, **14 tag groups** (Auth, Auth · Mobile, Auth · SSO, Public, and the Admin groups). - Two security schemes: `cookieAuth` (the `uomm_token` session cookie) and `bearerAuth` (mobile access-token JWT). - **28 reusable component schemas** for request/response bodies. **Per-endpoint annotations** — `#swagger.*` comments added next to every route (`auth`, `mobile`, `sso`, `public`, `admin`, plus `/api/health`). Response codes were taken from the controllers, not guessed: `400` validation, `401`/`403` auth, `404`, `409` conflicts, `429` rate-limits, `302` SSO redirects, `502` mail failure, and multipart for image uploads. **Wiring** — `server/src/app.js` serves `/api/docs` and `/api/docs.json`, guarded so a missing spec logs a warning and disables docs instead of crashing. **Docs** — `README.md` gains an "API documentation (Swagger)" section (URLs, how to Authorize in the UI, regeneration command) plus tech-stack and project-structure entries. ## Regenerating the spec After adding or changing a route: ```bash cd server npm run swagger # -> server/swagger/swagger-output.json ``` ## Verification - Generator run: **51 paths / 64 operations**, all with tags + summaries + responses, **0 problems**; the docs endpoints themselves are excluded from the spec. - Booted the app and hit the endpoints: `/api/docs.json` -> 200 (OpenAPI 3.0.0), `/api/docs/` -> 200 (UI renders), `/api/health` -> 200. - Existing test suite: **83/83 pass**. All edited files pass `node -c`. ## Reviewer note Response **codes** reflect what the handlers actually return. The request/response **body shapes** in the component schemas are reconstructed from the validators and controllers — worth a glance in the UI to confirm field names match the DB columns exactly before merging. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

wtclaude added 1 commit 2026-07-03 20:29:11 +00:00

Add Swagger/OpenAPI API docs (swagger-ui + swagger-autogen) a1f0675577

Generate an OpenAPI 3.0 spec from route annotations and serve it with
Swagger UI so the full REST API is browsable and testable.

- Add swagger-ui-express (runtime) and swagger-autogen (dev) deps, plus
  an `npm run swagger` script.
- server/swagger/swagger.js: generator config with API metadata, servers,
  14 tag groups, cookie + bearer security schemes, and 28 reusable
  component schemas. Follows the Express mount chain from src/app.js so
  generated paths are fully-qualified (/api/v1/...).
- Annotate every route (auth, mobile, sso, public, admin, health) with
  #swagger tags/summaries/parameters/request bodies/security and the
  actual response codes each handler returns (400/401/403/404/409/429/
  302/502, multipart uploads).
- Serve Swagger UI at /api/docs and the raw spec at /api/docs.json,
  guarded so a missing spec disables docs instead of crashing.
- Commit the generated swagger-output.json so docs work with no build
  step; swagger-autogen stays dev-only and is not needed at runtime.
- README: new "API documentation (Swagger)" section plus tech-stack and
  project-structure entries.

Covers 51 paths / 64 operations. Existing test suite (83) still passes.

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

whitlocktech approved these changes 2026-07-03 20:30:06 +00:00

whitlocktech merged commit 433e02d3ef into main

2026-07-03 20:30:16 +00:00

whitlocktech referenced this issue from a commit

2026-07-03 20:30:16 +00:00

Merge pull request 'Add Swagger/OpenAPI API docs (swagger-ui + swagger-autogen)' (#27) from feature/swagger-docs into main

whitlocktech deleted branch feature/swagger-docs

2026-07-03 20:30:17 +00:00

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: RunicGateway/website#27