openapi-sync.md

OpenAPI Contract Sync

What is the contract?

The file contracts/openapi/v1.json is the public OpenAPI 3.x contract that defines the Logion v1 API surface. The SDK (packages/client) and CLI (packages/cli) both derive their generated code from this contract.

Where does it come from?

The contract is generated by an internal service in the private Logion codebase and synced into this repository on merges to main. You will see PRs labeled automation/sync-openapi — these are produced by CI and should only be reviewed for accuracy, not edited manually.

Contributors cannot modify contracts/openapi/v1.json directly. If you need a change to the API contract (new endpoint, changed schema, etc.), please open a Discussion to propose it. The maintainers will evaluate and implement it upstream if accepted.

How to verify the contract locally

You can validate your code against the contract using the Prism mock server:

1. Install Node.js 18+ (if not already installed).

2. Start the mock server:

   make mock

   This starts Prism on port 4010.

3. Run your code against it:

   uv run logion health --base-url http://localhost:4010

4. Stop the mock server:

   make mock-stop

If the contract is correct, the mock server produces correct responses. If you find the mock returning unexpected data, the root cause is almost always a schema mismatch in the contract — not a Prism bug.

Regenerating client code

From packages/client/:

make generate-models     # generate Pydantic models from v1.json
make generate-operations  # generate low-level HTTP operations
make generate-client     # run both model + operation generation
make check-models         # verify models are up-to-date with contract
make check-operations     # verify operations are up-to-date with contract
make check-client         # verify everything is up-to-date

Never edit generated files directly. Always regenerate them from the contract.