OpenAPI

Workflow

1. Confirm API audience, lifecycle stage, and compatibility requirements.
2. Define resource model and operation semantics before schema expansion.
3. Build reusable component schemas and parameter conventions.
4. Encode auth, error formats, pagination, and idempotency patterns.
5. Establish linting and diff gates for contract changes.
6. Validate generated clients/servers against real traffic scenarios.
7. Govern versioning and deprecation policy with explicit timelines.

Preflight (Ask / Check First)

• OpenAPI target version (3.2 preferred when tooling supports it, otherwise 3.1).
• Consumer types (internal services, third parties, SDK generation).
• Backward-compatibility policy.
• Auth schemes and compliance constraints.
• Existing spec quality and tooling stack.