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>
5.5 KiB
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, documentv1) 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 usesMicrosoft.OpenApi2.x types; the transformers are written against that model (risk noted below).
Behaviour
- Committed file
openapi/slpsoftware.v1.json(repo root), the OpenAPI document of the SlpSoftware host (Offerings, Contact, Identity, Availability, Master, System). Written deterministically:serversremoved (it is derived from the request host), keys in the order the generator emits, 2-space indentation, LF line endings, trailing newline. - Snapshot test (pipeline test, needs the database like the other pipeline tests): fetches
/openapi/v1.jsonfrom the real host, normalizes it the same way, and compares it with the committed file; any drift fails the test with a message that namesUPDATE_OPENAPI=1. WithUPDATE_OPENAPI=1the test rewrites the file instead (and still passes), so regenerating is one command:UPDATE_OPENAPI=1 dotnet test --filter OpenApiSnapshot. - Contact contract details in the document (module-level transformers):
- Reusable
components.responses:Validation(400,application/problem+json,ValidationProblemwitherrorsmap of arrays of the codesrequired|tooLong|invalid|expired),TooLarge(413),RateLimited(429 with theRetry-Afterheader,Problem), plus schemasProblemandValidationProblem; referenced by the contact operations. POST /api/v1/contact-messages: required header parameterIdempotency-Key(uuid); request body schema marksname, email, subject, message, hpCheck, tokenas required with the contract'smaxLengthvalues (100, 254, 100, 2000, 0 forhpCheck),captchaTokennullable; responses 202/400/413/429 (404 is documented as "form closed").GET /api/v1/contact-messages/token: 200 (ContactToken:token,minSeconds,captchanullable 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).
- Reusable
- cms-client note: the file is the single source for generated types; the Andrea host will get
openapi/andreaslopfotografie.v1.jsonwhen 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]onGetTokenandSubmit(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 fromContactModule.RegisterServicesviaservices.Configure<OpenApiOptions>("v1", ...). - Step 3 — Snapshot test + helper in
Contact.Tests/Pipeline/OpenApiSnapshotTests.cs: normalization (dropservers, stable formatting), repo-root lookup (walk up toSlpModularCms.sln),UPDATE_OPENAPI=1rewrite, 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).