Generate and verify OpenAPI and the TypeScript client #10

New issue

Open

opened 2026-11-01 20:11:30 +00:00 by viacheslavshuka · 0 comments

viacheslavshuka commented

2026-11-01 20:11:30 +00:00

Owner

The generated schema is the public API contract. Source changes must update the committed OpenAPI and TypeScript artifacts together.

Scope

Export /openapi.json from a running disposable application. Generate types with openapi-typescript and use openapi-fetch for typed method-and-path calls.

Acceptance criteria

One command starts or addresses the disposable service, exports its schema, and deterministically generates committed artifacts. It uses synthetic configuration without production credentials.
Repeating generation without source changes produces no diff. CI regenerates and fails on missing or stale committed output. Contributors correct source declarations instead of editing generated files.
Every public operation has a stable unique operation ID, meaningful summary, description, and domain tag. Descriptions state applicable permissions and side effects.
Schema checks cover references, input constraints, request/response examples, and actual JSON serialization. Required, omitted, nullable, defaulted, and unknown fields remain distinguishable.
UUIDs, timezone-aware timestamps, decimals, and integers outside JavaScript's safe range have explicit wire representations whenever the API exposes them.
Supported success and error responses declare their status, body, media type, and relevant headers. Bodyless responses remain bodyless in OpenAPI and actual responses.
fastapi-error-map produces mapped error documentation with typed bodies and stable codes. Supplemental response metadata cannot overwrite accurate generated error schemas.
Schemathesis exercises actual responses against the exported schema using explicit test identity and data. Authenticated operations must reach their successful paths when present.
Generated types compile with the frontend and support typed method-and-path calls. Tests cover invalid request typing and representative response typing. Type generation does not claim runtime response validation.
API changes include a compatibility review and source-level corrections. Existing operation IDs survive internal refactors.

Validation

Exercise malformed references, duplicate operation IDs, stale output, inconsistent examples, and a bodyless response in disposable validation fixtures. Demonstrate an actual schema-derived request against the running service. Add stateful links as product operations introduce related workflows.

Dependencies

#6: Start the FastAPI runtime with owned database resources. Schema export needs the running API.
#7: Create the React application with locked frontend tooling. Generation and consumer checks need the TypeScript toolchain.

#13: Enforce complete validation in the shared Forgejo runner flow

The generated schema is the public API contract. Source changes must update the committed OpenAPI and TypeScript artifacts together. ## Scope Export `/openapi.json` from a running disposable application. Generate types with openapi-typescript and use openapi-fetch for typed method-and-path calls. ## Acceptance criteria - One command starts or addresses the disposable service, exports its schema, and deterministically generates committed artifacts. It uses synthetic configuration without production credentials. - Repeating generation without source changes produces no diff. CI regenerates and fails on missing or stale committed output. Contributors correct source declarations instead of editing generated files. - Every public operation has a stable unique operation ID, meaningful summary, description, and domain tag. Descriptions state applicable permissions and side effects. - Schema checks cover references, input constraints, request/response examples, and actual JSON serialization. Required, omitted, nullable, defaulted, and unknown fields remain distinguishable. - UUIDs, timezone-aware timestamps, decimals, and integers outside JavaScript's safe range have explicit wire representations whenever the API exposes them. - Supported success and error responses declare their status, body, media type, and relevant headers. Bodyless responses remain bodyless in OpenAPI and actual responses. - fastapi-error-map produces mapped error documentation with typed bodies and stable codes. Supplemental response metadata cannot overwrite accurate generated error schemas. - Schemathesis exercises actual responses against the exported schema using explicit test identity and data. Authenticated operations must reach their successful paths when present. - Generated types compile with the frontend and support typed method-and-path calls. Tests cover invalid request typing and representative response typing. Type generation does not claim runtime response validation. - API changes include a compatibility review and source-level corrections. Existing operation IDs survive internal refactors. ## Validation Exercise malformed references, duplicate operation IDs, stale output, inconsistent examples, and a bodyless response in disposable validation fixtures. Demonstrate an actual schema-derived request against the running service. Add stateful links as product operations introduce related workflows. ## Dependencies - [#6: Start the FastAPI runtime with owned database resources](https://code.viacheslavshuka.com/viacheslavshuka/quorum/issues/6). Schema export needs the running API. - [#7: Create the React application with locked frontend tooling](https://code.viacheslavshuka.com/viacheslavshuka/quorum/issues/7). Generation and consumer checks need the TypeScript toolchain. ## Related work - [#13: Enforce complete validation in the shared Forgejo runner flow](https://code.viacheslavshuka.com/viacheslavshuka/quorum/issues/13)

viacheslavshuka referenced this issue

2026-11-01 20:11:42 +00:00

Keep browser data useful during slow or lost connections #24

viacheslavshuka referenced this issue

2026-11-01 20:11:48 +00:00

Scan the disposable authenticated API with ZAP #31

viacheslavshuka referenced this issue

2026-11-01 20:11:49 +00:00

Use one application version across builds and release artifacts #32

viacheslavshuka referenced this issue

2026-11-01 20:11:52 +00:00

Create and reuse author blocks, rounds, and packages #35