# Code Generation Plan — CMS-U3b openapi-export Phase 1, right after CMS-U3. Contract: "the definitive OpenAPI document is generated by the CMS and committed, so `cms-client` generates its types from it" (§ 8, FR-H). Scope: the SlpSoftware host's API document as a committed file plus a test that keeps it current, and the contact contract details in it (reusable problem responses, required header, required request fields). No behaviour change of any endpoint. ## Findings - The host already registers `services.AddOpenApi()` (Core, document `v1`) and, in Development only, `app.MapOpenApi()` which serves `/openapi/v1.json`; the pipeline test host runs in Development, so the document can be fetched over HTTP from the real composed host (no internal API needed). - The shared registration lives in a Core file the ASF branch also changes. Everything contact-specific is therefore added **from the Contact module** through named options (`services.Configure("v1", ...)`), leaving Core untouched. - `.NET 10`'s OpenAPI uses `Microsoft.OpenApi` 2.x types; the transformers are written against that model (risk noted below). ## Behaviour 1. **Committed file** `openapi/slpsoftware.v1.json` (repo root), the OpenAPI document of the SlpSoftware host (Offerings, Contact, Identity, Availability, Master, System). Written deterministically: `servers` removed (it is derived from the request host), keys in the order the generator emits, 2-space indentation, LF line endings, trailing newline. 2. **Snapshot test** (pipeline test, needs the database like the other pipeline tests): fetches `/openapi/v1.json` from the real host, normalizes it the same way, and compares it with the committed file; any drift fails the test with a message that names `UPDATE_OPENAPI=1`. With `UPDATE_OPENAPI=1` the test rewrites the file instead (and still passes), so regenerating is one command: `UPDATE_OPENAPI=1 dotnet test --filter OpenApiSnapshot`. 3. **Contact contract details in the document** (module-level transformers): - Reusable `components.responses`: `Validation` (400, `application/problem+json`, `ValidationProblem` with `errors` map of arrays of the codes `required|tooLong|invalid|expired`), `TooLarge` (413), `RateLimited` (429 with the `Retry-After` header, `Problem`), plus schemas `Problem` and `ValidationProblem`; referenced by the contact operations. - `POST /api/v1/contact-messages`: required header parameter `Idempotency-Key` (uuid); request body schema marks `name, email, subject, message, hpCheck, token` as required with the contract's `maxLength` values (100, 254, 100, 2000, 0 for `hpCheck`), `captchaToken` nullable; responses 202/400/413/429 (404 is documented as "form closed"). - `GET /api/v1/contact-messages/token`: 200 (`ContactToken`: `token`, `minSeconds`, `captcha` nullable object) and 429; 404 "form closed". - Attributes (`[ProducesResponseType]`) on the public contact actions drive the operations; the transformers only add what attributes cannot express (components, header, required/maxLength). 4. **cms-client note**: the file is the single source for generated types; the Andrea host will get `openapi/andreaslopfotografie.v1.json` when it exists on the base branch (name = host name); this unit documents the convention in the file's README line in the summary. ## Steps - [x] **Step 1 — Attributes**: `[ProducesResponseType]` on `GetToken` and `Submit` (and `[ProducesResponseType<...>]` for the offerings list is already inferred by return types; nothing else is touched). - [x] **Step 2 — Transformers** in `Modules.Contact/OpenApi/`: `ContactOpenApiDocumentTransformer` (components), `ContactOpenApiOperationTransformer` (header, response refs), `ContactOpenApiSchemaTransformer` (required/maxLength). Registered from `ContactModule.RegisterServices` via `services.Configure("v1", ...)`. - [x] **Step 3 — Snapshot test + helper** in `Contact.Tests/Pipeline/OpenApiSnapshotTests.cs`: normalization (drop `servers`, stable formatting), repo-root lookup (walk up to `SlpModularCms.sln`), `UPDATE_OPENAPI=1` rewrite, a failing message with the exact regeneration command. Plus unit assertions on the fetched document (not only equality with the file): the contract details in item 3 exist (header required, reusable responses present, required fields and maxLength), so a regenerated file cannot silently lose them. - [x] **Step 4 — Generate and commit** `openapi/slpsoftware.v1.json`; review it (no PII, no secrets, no host names, no example addresses). - [x] **Step 5 — Verification (automatic)**: build; Contact.Tests (pipeline against a temporary MariaDB); full solution tests; real output. The test is run twice: once with `UPDATE_OPENAPI=1`, once without (must pass unchanged). - [x] **Step 6 — Docs/commit**: summary (how to regenerate, how the frontend consumes it, convention per host); one commit; no push. ## Explicitly NOT touched Core (`AddOpenApi`, `MapOpenApi`), any endpoint behaviour, other modules' controllers (their operations simply appear in the document as generated), the Andrea host (not on the base branch), frontend. ## Risks / open points - The Microsoft.OpenApi 2.x model differs from 1.x examples found online; if a detail cannot be expressed through the transformer API, the unit documents it in the summary instead of faking it, and the test asserts what the document really contains. - The file will be large (the whole host API). It is committed as is; reviewers diff it like code. - Needs SLS confirmation: file name per host: `openapi/slpsoftware.v1.json` (approved).