Chris Butcher, Python automation

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

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

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.