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:
+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.
|
||||
Reference in New Issue
Block a user