OpenAPI Specification

Design, validate, and maintain OpenAPI 3.x specifications for REST API contracts. Covers schema patterns, security schemes, versioning, and code generation integration.

When to Use This Skill

• Creating a new OpenAPI specification from scratch
• Adding endpoints or schemas to an existing spec
• Reviewing or validating an API contract for correctness
• Setting up code generation from OpenAPI definitions
• Designing reusable schema components for large APIs
• Implementing security schemes in API specifications
• Managing API versioning and deprecation

Quick Reference

Resource	Purpose	Load when
references/spec-patterns.md	Schema patterns, security schemes, validation, versioning, reusable components	Designing or reviewing specs

---

Workflow

Phase 1: Design       → Define API overview, resources, and operations
Phase 2: Schema       → Build data models with reusable components
Phase 3: Validate     → Lint and verify the spec for correctness
Phase 4: Integrate    → Generate docs, SDKs, and contract tests

---

Phase 1: API Design

Start with a high-level design before writing the spec:

1. Identify resources -- what nouns does this API expose?
2. Map operations -- what CRUD and custom actions apply to each resource?
3. Define relationships -- how do resources reference each other?
4. Plan authentication -- what security schemes are needed?
5. Set conventions -- naming style, pagination, error format

Spec Skeleton

openapi: 3.1.0
info:
  title: [API Name]
  version: 1.0.0
  description: [What this API does]
paths:
  /resources:
    get:
      summary: List resources
      operationId: listResources
    post:
      summary: Create a resource
      operationId: createResource
  /resources/{id}:
    get:
      summary: Get a resource
      operationId: getResource
components:
  schemas: {}
  securitySchemes: {}

---

Phase 2: Schema Design

Build data models using components/schemas for reuse:

• Use $ref to reference shared schemas -- never duplicate definitions
• Apply allOf for composition, oneOf / anyOf for polymorphism
• Add example values to every schema and property
• Use required arrays explicitly -- don't rely on implicit behavior
• Document nullable fields with type: [string, "null"] (3.1) or nullable: true (3.0)

---

Phase 3: Validate

Run validation before committing any spec changes:

# Spectral (recommended)
spectral lint openapi.yaml

# Redocly
redocly lint openapi.yaml

# swagger-cli
swagger-cli validate openapi.yaml

Common Validation Issues

Issue	Fix
Missing operationId	Add unique operationId to every operation
Unused schema	Remove from components or add a $ref
Missing response description	Add description to every response code
Path parameter not in path	Match {param} in path with parameter definition
No 2xx response defined	Add at least one success response per operation

---

Phase 4: Integrate

Use the validated spec to generate downstream artifacts:

• Documentation: Redoc, Swagger UI, Stoplight
• Client SDKs: openapi-generator, autorest, orval
• Server stubs: openapi-generator with server templates
• Contract tests: Schemathesis, Dredd, Prism

---

Quality Checklist

• All paths have operationIds
• HTTP methods match resource actions (GET reads, POST creates, etc.)
• Every response has a description and schema
• Security requirements defined at operation or global level
• Examples provided for request and response bodies
• Consistent naming conventions (camelCase, snake_case -- pick one)
• Deprecation fields set on sunset endpoints
• Spec passes linter with zero errors

---

Anti-Patterns

• Do not inline schemas -- use $ref to components/schemas for anything reused
• Do not mix API versions in a single spec file
• Do not use 200 OK for create operations -- use 201 Created
• Do not omit error response schemas -- document 4xx and 5xx consistently
• Do not use additionalProperties: true without clear justification