OpenAPI skeleton
The problem
An API exists but the docs are missing or wrong, so every integration starts with guessing at paths, fields, and error shapes.
The artefact
A hand-written OpenAPI 3.1 YAML skeleton for one small CRUD resource (items), plus a tiny FastAPI app that implements it. The YAML is the contract: paths, schemas, examples, and error responses for 400, 404, 409, 422, and 500, all shaped as one Error schema with code and message. The artefact README, YAML, and source are copied under files on this page.
Input and output sample
Input:
POST /items
{"name": "widget", "quantity": 3}
Output:
{"id": 1, "name": "widget", "quantity": 3}
{"code": "not_found", "message": "Item 42 does not exist."}
A second POST with the same name returns 409 with code conflict. A negative quantity returns 422. The served contract reads at /openapi.json, with interactive docs at /docs.
What can break
- Docs that drift from the served API, so clients code against paths that do not exist
- Error responses with a different shape per endpoint, so error handling turns into guesswork
- Examples that no longer match the schemas they sit next to
The fix or design choice
One Error schema with code and message across all five error responses, and a conformance test that fetches /openapi.json from the app and asserts every YAML path and method is served, the schemas exist, and each error response uses the Error schema. The app validates quantity 0 or greater and name non-empty through Pydantic, matching the YAML constraints. The app keeps items in memory, so it is a starting point, not a finished service.
Verification log
- 2026-11-19: test suite run from a clean shell, 5 passed
- The openapi_spec_validator package is not in the shared venv, so validation ran through yaml.safe_load plus structural asserts in the tests: version, paths, schema names, Error required fields, and the five named error responses
Verified 2026-11-19
Files
Price shape
Docs and QA from $400 fixed. The first deliverable is the spec for your resource with examples and error shapes, plus the conformance check that keeps it honest.
Start here
Email one example request and one example response from your API. I reply with the fixed quote and the spec outline.