mirror of
https://github.com/strelov1/freehire.git
synced 2026-11-15 14:40:40 +08:00
Ilya Strelov
a38a33dbb5
* refactor(api): generate the API reference from the contract The public API docs (/docs/api, /docs/api/internal, docs/API*.md) were rendered from a second, hand-written spec in web/src/lib/docs/api-spec-groups, which had already drifted from the server. The reader-facing text now lives in typespec/ and the generator reads openapi/api.openapi.json. - typespec: @summary, doc comments on operations, params and body fields, and @opExample from the hand spec; overview and tag descriptions in docs.tsp. @useAuth on every operation, matching the Fiber gate in front of it (cookie by default, SessionOrKey for mw.key, NoAuth for public routes); x-audience marks moderator routes and hides API-key management and the /fit aliases. - ogen reads a copy without security (scripts/openapi-ogen-input.mjs), so apigen changes only in doc comments and route summaries; the gates stay in the router. - web/scripts/gen-api-docs.mjs renders all four documents from the contract plus api-supplement.openapi.json, the routes still outside the contract; gen-openapi.mjs, its smoke test and the hand spec are deleted. The audience comes from security. - The reference now covers 389 operations instead of 254. * fix(api): address review findings on the generated reference - List shared ($ref) parameters in the Markdown tables; the talent filters were missing. - Mark /me/autofill/run extension-only (x-audience), so it leaves the external reference. - Correct the plan description and example (free has no allowance) and the match-text example field (coverage_percent). - Supplement: 204 for the bodyless deletes and logout-all, multipart bodies for the photo, speech and CV uploads. - Escape backslashes in table cells; anchor the smoke's base-URL check (CodeQL). - make api-contract compiles into a scratch dir under openapi/ and renames the result over the document, so the api-docs-drift hook, running in parallel, never reads it half-done.