OpenAPI Specification
The OpenAPI Specification is a language-neutral way to describe an HTTP API. It lists actions, inputs, data shapes, security methods, replies, and reusable schemas.
Another example
A partner API describes `POST /claims` and its required idempotency header. It also lists the OAuth scope, JSON Schema rules, 201 and problem replies, and examples with fake data. CI blocks a breaking reply that was not documented. Generated clients are still reviewed instead of trusted without checks.
Main parts
- 01API metadata and servers
- 02Paths and operations
- 03Schemas, security, and responses
Use it when
Use it as a contract people can review for docs, checks, mock servers, client generation, and compatibility tests.
Do not use it when
Generated docs do not replace real examples, authorization tests, checks at runtime, or clear production behavior.
Name used in code
openapi document: paths, operations, components/schemas, securitySchemes, responses Before you ship
Check contracts and invariants, authorization, and input limits. Test retries, one-time effects, timeouts, and partial failures. Verify data integrity, compatibility, monitoring, recovery, and rollback.
Outcome: Design or review OpenAPI Specification for this system while keeping data correct, secure, and easy to operate. User context: A partner API describes `POST /claims` and its required idempotency header. It also lists the OAuth scope, JSON Schema rules, 201 and problem replies, and examples with fake data. CI blocks a breaking reply that was not documented. Generated clients are still reviewed instead of trusted without checks. Technical concept or control: OpenAPI Specification. Why it fits: Use it as a contract people can review for docs, checks, mock servers, client generation, and compatibility tests. Do not use it when: Generated docs do not replace real examples, authorization tests, checks at runtime, or clear production behavior. Engineering requirements: Define inputs, outputs, contracts, and rules that must always hold. Set authorization and input checks. Define failures, timeouts, retries, one-time effects, data moves, and compatibility limits. Operations: Add useful signals and logs that hide sensitive data. Set capacity limits and write an operator guide. Test recovery and rollback. Acceptance criteria: Contract and failure-path tests pass. Data and authorization rules still hold during retries and partial failures. Check performance limits, monitoring, recovery, and rollback. Evidence and limits (evidence boundary): A formal document may still be a draft, release candidate, or final version. Check its status and browser or platform support. Unknowns to confirm: Where the code runs, data stores, traffic shape, consistency needs, and the security boundary. Also confirm the compatibility period, service goals, and rollback limits.
Check this request
Review the current use of OpenAPI Specification. Definition: The OpenAPI Specification is a language-neutral way to describe an HTTP API. It lists actions, inputs, data shapes, security methods, replies, and reusable schemas. Release checks: Check contracts and invariants, authorization, and input limits. Test retries, one-time effects, timeouts, and partial failures. Verify data integrity, compatibility, monitoring, recovery, and rollback. Before changing code, report the evidence you found, gaps, severity, and the smallest safe fix.