# Phase 7 — OpenAPI 3.1 Contract

## Source of truth

The authoritative API surface is `routes/api.php` and `routes/admin.php`. The generator does not execute the application; it parses the route declarations deterministically.

## Generated artifacts

- `docs/openapi.json` — OpenAPI 3.1 contract with all route operations.
- `docs/ERROR_CODES.md` — inventory of error-code identifiers found in `src/`.
- `docs/openapi.postman.json` — generated Postman collection for smoke execution.

## Regeneration

```bash
php tools/generate-openapi.php
php tools/openapi-check.php
```

The parity gate must remain exactly `183/183` operations.

## Dependency

Phase 7 declares `zircote/swagger-php:^4.11` for attribute-based contract enrichment. The checked-in JSON is deterministic and route-complete even before controller attributes are enriched, so CI does not depend on executing the application during generation.

After applying the patch, run:

```bash
composer update zircote/swagger-php --with-dependencies
composer openapi:check
```

The OpenAPI contract intentionally starts with shared response/request envelopes. Endpoint-specific request/response schemas should be enriched from the controller validation and response implementations without changing URL paths, methods, response codes, or error semantics.
