Fill in these first
- Framework: [e.g. Laravel, Express, Django REST framework, Spring Boot]
- Route definitions: [paste]
- Handlers and validation rules for each route: [paste]
- Authentication method: [e.g. bearer token, API key header, session cookie]
- Base URL placeholder: [e.g. https://api.example.com/v1]
- Error response shape used today: [paste one example]
Task
Write an OpenAPI 3.1 document that matches the code exactly as it behaves now.
Output format
- One YAML code block: info, servers, security schemes, paths, and shared schemas under components.
- For each operation: summary, operationId, parameters, request body, success response, and every error the code can return.
- One realistic example for each request and response body.
- A gap list: | Route | What the code does that is unclear | Question for the team |
Rules
- Describe only what the code does; never add endpoints or fields that are not there.
- Reuse schemas through references instead of repeating them.
- Mark fields required only when validation enforces it.
- Mark any inferred type with a short description saying it was inferred.






