OpenAPI Specification (Deep Workflow)
OpenAPI is the contract between teams and tools. Quality comes from consistent schemas, realistic examples, and lint rules that catch breaking changes early.
When to Offer This Workflow
Trigger conditions:
- New REST API; public or partner surface
- Codegen for clients/servers; API gateway validation from spec
- Drift between docs and implementation
Initial offer:
Use six stages: (1) workflow choice & ownership, (2) info & versioning, (3) resources & operations, (4) schemas & components, (5) security & errors, (6) lint, compatibility & publish). Confirm OpenAPI 3.x and style guide.
Stage 1: Workflow & Ownership
Goal: Design-first (spec → implement) vs code-first (annotations → export)—pick one per service and enforce.
Ownership
- Who approves breaking changes; where spec lives in repo
Exit condition: Single source of truth for the API contract.
Stage 2: Info & Versioning
Goal: info.title, version scheme aligned with URL or header versioning strategy.
Practices
- Deprecation policy in description or extension fields
Stage 3: Resources & Operations
Goal: RESTful naming where appropriate; operationId stable for codegen.
Practices
- Pagination (
cursor/page), filtering, sort documented - Idempotency (
Idempotency-Key) for unsafe retries when relevant
Stage 4: Schemas & Components
Goal: components/schemas reused; nullable vs optional correct in JSON Schema sense.
Practices
- OneOf discriminated unions for polymorphic payloads when needed
- Examples per schema for human and machine readers
Stage 5: Security & Errors
Goal: securitySchemes (Bearer, OAuth2) applied per operation or globally.
Errors
- Problem Details (
application/problem+json) pattern with stable type URIs
Stage 6: Lint, Compatibility & Publish
Goal: Spectral or vacuum rules in CI; openapi-diff on PRs.
Publish
- Docs portal (Swagger UI, Redoc); postman collections optional
Final Review Checklist
- [ ] Single ownership and design-first or code-first discipline
- [ ] Versioning and deprecation story clear
- [ ] Operations complete with pagination/errors as needed
- [ ] Reusable components and examples
- [ ] Security and error model consistent
- [ ] CI lint and breaking-change detection
Tips for Effective Guidance
- Examples should be copy-paste valid—catch enum drift.
- Nullable in OpenAPI 3.1 aligns with JSON Schema—mind 3.0 differences when mixing.
- Internal APIs still benefit from the same rigor—future you is a partner team.
Handling Deviations
- GraphQL elsewhere: OpenAPI for REST edge only—don’t force one doc for both.