# OpenAPI skeleton

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 app keeps items in memory, so it is a starting
point, not a finished service.

## Run

```bash
cd ~/freelance-engine/projects/dev-artefacts/openapi-skeleton
~/freelance-engine/.venv/bin/python -m uvicorn app:app --port 8012
```

Then read the served contract at http://127.0.0.1:8012/openapi.json
or the interactive docs at http://127.0.0.1:8012/docs.

## Try it

```bash
curl -s -X POST localhost:8012/items \
  -H 'content-type: application/json' \
  -d '{"name": "widget", "quantity": 3}'

curl -s localhost:8012/items
curl -s localhost:8012/items/42
```

Sample responses:

```json
{"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.

## Lint the YAML

When openapi_spec_validator is installed:

```bash
~/freelance-engine/.venv/bin/python -m openapi_spec_validator openapi.yaml
```

It is not installed in the shared venv, so the test suite covers
the same ground with yaml.safe_load plus structural asserts:
version, paths, schema names, Error required fields, and the five
named error responses. The conformance test then fetches
/openapi.json from the app and asserts every YAML path and method
is served, the four schemas exist, and each error response uses
the Error schema.

## Tests

```bash
~/freelance-engine/.venv/bin/python -m pytest tests/ -q
```

## Verification log

- 2026-11-19: test suite run from a clean shell, 5 passed.
- openapi_spec_validator is absent from the venv, so validation
  ran through the structural asserts in the tests, as documented
  above. Install it only if a stricter lint is wanted later.
- The app validates quantity 0 or greater and name non-empty
  through Pydantic, matching the YAML constraints.
