OpenAPI Specifications
An OpenAPI document manages API paths, requests, responses, authentication, and error contracts in a structured format.
Before creating one
Review:
- User and system flows
- Requirements and permissions
- States and exceptions
- Related data structures
- Shared error and authentication rules
- Versioning and compatibility policy
Create an OpenAPI document
Use the web app or ask an Agent.
Read the project source of truth, related Diagrams, and ERD, then create an OpenAPI draft for [feature scope].
Do not adopt the draft as an implementation contract immediately. Compare it with the product flow, data structure, and policy.
Read and update
An Agent can read the OpenAPI source and replace its full content. When reading, it can also inspect structural information such as format, specification version, path count, and operation count.
If a specification already exists for the same API, identify the affected paths and update it instead of creating a duplicate.
Review
- Are all paths required by the user flow present?
- Do request and response fields match the data structure?
- Are authentication and authorization explicit?
- Are errors and exceptional responses defined?
- Are state changes and idempotency rules correct?
- Does the change break existing consumers?
Record important contract decisions and their reasons in Markdown. Link implementation and test work in Kanban.
Next, go to File Documents to manage source materials and output files.