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>
This commit is contained in:
@@ -5,7 +5,7 @@
|
||||
- **Feature Slug**: contact-forms-module
|
||||
- **Project Type**: Brownfield
|
||||
- **Start Date**: 2026-11-09
|
||||
- **Current Stage**: CONSTRUCTION - CMS-U3b and CMS-U4 Code Generation Part 1 (plans awaiting approval by Redesign - SLS)
|
||||
- **Current Stage**: CONSTRUCTION - CMS-U3b built and committed; CMS-U4 in progress
|
||||
- **Branch**: feature/contact-forms-module (worktree ..SlpModularCms-contact-forms, from master d9cc539; main checkout stays on feature/identity-email-notifications — never switch it)
|
||||
|
||||
## Workspace State
|
||||
|
||||
+25
@@ -0,0 +1,25 @@
|
||||
# CMS-U3b openapi-export: code summary
|
||||
|
||||
## Result
|
||||
Committed `openapi/slpsoftware.v1.json`: the OpenAPI 3.1 document of the SlpSoftware host (Offerings, Contact, Identity, Availability, Master, System). **Convention: one file per host, named after the host** (`openapi/slpsoftware.v1.json` now, `openapi/andreaslopfotografie.v1.json` when that host exists on the base branch). It is the single source from which the frontend client (`cms-client`) generates its types.
|
||||
|
||||
Regenerate after an intended API change: `UPDATE_OPENAPI=1 dotnet test --filter OpenApiSnapshot` (needs the database like the other pipeline tests). Without the variable the same test fails when the served document differs from the file, with that command in its message (drift detection was verified by changing one value in the file).
|
||||
|
||||
Normalized form (so the diff is meaningful): no `servers` (derived from the request host), object keys in ordinal order everywhere, 2-space indentation, LF, trailing newline. Reviewed for hosts, addresses and secrets; the tests assert there are none.
|
||||
|
||||
## Contact contract in the document (module-level, Core untouched)
|
||||
`ContactOpenApiDocumentTransformer`, registered from `ContactModule` through the named options of document `v1`:
|
||||
- Reusable `components.responses`: `Validation` (400, problem+json, schema `ValidationProblem` with `errors` = map of field name -> array of `required|tooLong|invalid|expired`), `TooLarge` (413), `RateLimited` (429 with the `Retry-After` header); schemas `Problem`, `ValidationProblem`.
|
||||
- `POST /api/v1/contact-messages`: required header `Idempotency-Key` (uuid); request body required, exactly one `ContactMessageRequest` (`required`: name, email, subject, message, hpCheck, token; `maxLength` 100/254/100/2000/0, plain `string` types; `captchaToken` nullable); responses 202, 400, 404 (form closed), 413, 429.
|
||||
- `GET /api/v1/contact-messages/token`: 200 (`ContactTokenResponse`), 404 (form closed), 429.
|
||||
- The contact controller is not an `[ApiController]` (own error shape), so it carries `[ApiExplorerSettings(IgnoreApi = false)]` to appear in the document; `[ProducesResponseType]` attributes (with explicit content types) drive its operations.
|
||||
|
||||
## Notes
|
||||
- Microsoft.OpenApi 2.x model: everything above could be expressed through the document transformer; nothing had to be faked. Minor generator quirks kept as generated (e.g. nullable unions elsewhere in the document).
|
||||
- The document is of the host as composed: operations of every loaded module appear. Routes that are closed at runtime (`Contact:Enabled=false`) are still documented; the 404 "form closed" response says so.
|
||||
|
||||
## Side fix found while doing this
|
||||
Problem details of the 400 answer are explicitly `application/problem+json` again after a class-level `[Produces]` experiment was rejected (it overrides the content type); covered by the existing pipeline test and a new controller assertion.
|
||||
|
||||
## Verification (real output)
|
||||
Build 0 errors. Contact.Tests 117 passed (4 new OpenApiSnapshot tests: equality with the committed file, contract content incl. header/required/maxLength/reusable responses/error codes, no hosts/addresses/secrets, deterministic normalization), Core 205, Availability 95, Offerings 86, Identity 37, Master 57, Api.Tests 4; temporary MariaDB used and removed afterwards.
|
||||
+9
-9
@@ -8,22 +8,22 @@ Phase 1, right after CMS-U3. Contract: "the definitive OpenAPI document is gener
|
||||
- `.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/cms-api.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.
|
||||
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 its own file when it exists on the base branch (name per host, e.g. `openapi/andrea.v1.json`); this unit documents the convention in the file's README line in the summary.
|
||||
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/cms-api.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.
|
||||
- [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<OpenApiOptions>("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.
|
||||
@@ -31,4 +31,4 @@ Core (`AddOpenApi`, `MapOpenApi`), any endpoint behaviour, other modules' contro
|
||||
## 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 `openapi/cms-api.v1.json` for the SlpSoftware host (per-host naming convention proposed above).
|
||||
- Needs SLS confirmation: file name per host: `openapi/slpsoftware.v1.json` (approved).
|
||||
|
||||
Reference in New Issue
Block a user