OpenAPI Schema
The OpenAPI 3.1 schema is the API documentation source of truth. It should power interactive reference pages, SDK generation, contract tests, and backend review.
| Location | Purpose |
|---|---|
api-reference/openapi.yaml | Repository source file reviewed with backend changes. |
/openapi.yaml | Published static copy served by the docs site. |
Current starter endpoint
Section titled “Current starter endpoint”The first implemented schema section documents POST /analyses, which uploads a raw FID file and starts spectral analysis. Every endpoint added to the backend should include:
- HTTP method and path.
- Description in user language.
- Request body schema.
- Success response schema.
- Error response schema.
- Tested curl example in the corresponding guide.
Review gate
Section titled “Review gate”Never merge a backend endpoint without updating the schema, validating it, and testing the documented request against sandbox.