Files
slp-modular-cms/aidlc-docs/features/contact-forms-module/construction/plans/cms-u3b-openapi-export-code-generation-plan.md
T
SluijsensandClaude Sonnet 5.5 f8d45eef54 OpenAPI-document van de SlpSoftware-host vastgelegd met snapshot-test en contactcontract
openapi/slpsoftware.v1.json is de bron voor de gegenereerde frontend-types; een test haalt het document van de echte host op en faalt bij afwijking (UPDATE_OPENAPI=1 herschrijft het bestand). De contactmodule voegt de herbruikbare foutresponses, de verplichte Idempotency-Key en de verplichte velden met maximale lengtes toe via een documenttransformer, zodat Core ongemoeid blijft.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-10 13:07:28 +01:00

5.5 KiB

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<OpenApiOptions>("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

  • Step 1 — Attributes: [ProducesResponseType] on GetToken and Submit (and [ProducesResponseType<...>] for the offerings list is already inferred by return types; nothing else is touched).
  • Step 2 — Transformers in Modules.Contact/OpenApi/: ContactOpenApiDocumentTransformer (components), ContactOpenApiOperationTransformer (header, response refs), ContactOpenApiSchemaTransformer (required/maxLength). Registered from ContactModule.RegisterServices via services.Configure<OpenApiOptions>("v1", ...).
  • 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.
  • Step 4 — Generate and commit openapi/slpsoftware.v1.json; review it (no PII, no secrets, no host names, no example addresses).
  • 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).
  • 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).