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.