openapi-design

---
name: openapi-design
description: Best practices for OpenAPI-first API design, linting, versioning, and code generation.
license: MIT
---

# OpenAPI Design

Purpose: Ensure consistent, versioned API contracts suitable for code generation, client integration, and CI gating.

Overview
- Favor contract-first design: write or finalize the OpenAPI YAML/JSON before implementing controllers.
- Keep OperationIDs stable and descriptive; they drive codegen and client SDK method names.

Tools (examples)
- Linting/validation: `@stoplight/spectral` (Spectral), `openapi-cli`, `oas-validator`
- Generation: `openapi-generator-cli` or `openapi-generator` Docker image
- Local checks: `ajv` for JSON Schema example validation, `yamllint` for formatting
- CI: run Spectral + generator + compile step as gating checks

Key topics & guidance
- Contract-first design and stable `operationId`s: prefer semantic, version-proof names.
- Security schemes: model JWT/OAuth2/mTLS explicitly under `components/securitySchemes` and attach to operations.
- Linting + automated validation: add Spectral ruleset for project conventions; fail CI on lint errors.
- Versioning: support `major.minor` in API path or header; document breaking changes in changelog.
- Codegen templates: keep generator templates in `.github/templates/openapi/` and pin generator version.

Required inputs
- Product/feature API requirements (endpoints, payloads, auth expectations)
- Example request/response payloads (JSON fixtures) to validate schemas

Outputs
- A linted OpenAPI file (`openapi.yaml` or `openapi.json`)
- Contract-change checklist to attach to PRs
- Codegen configuration (generator args, template overrides)

Quick checklist (PR / author)
- Add or update `openapi.yaml` in `specs/` or feature folder
- Run: `npx @stoplight/spectral lint specs/openapi.yaml`
- Run generator smoke: `openapi-generator-cli generate -i specs/openapi.yaml -g spring -o build/generated` then compile the generated module
- Include JSON example files and run schema validation: `node ./scripts/validate-examples.js specs/openapi.yaml examples/`
- Update changelog with contract changes and migration notes

CI snippet (example)
```yaml
- name: Lint OpenAPI
	run: npx @stoplight/spectral lint specs/openapi.yaml --ruleset .spectral.yml

- name: Generate and build scaffold
	run: |
		openapi-generator-cli generate -i specs/openapi.yaml -g spring -o build/generated --skip-validate-spec
		pushd build/generated && mvn -q -DskipTests package || exit 1
```

Contract change policy
- Small, additive changes (non-breaking) may be approved with normal PR flow.
- Breaking changes require: migration notes, version bump, consumer notification, and feature-flag/compatibility layer when possible.
- Add a `contract-change.md` file for any breaking change detailing affected consumers and rollout plan.

Example generator command
```
openapi-generator-cli generate \
	-i specs/openapi.yaml \
	-g spring \
	-o modules/generated-control-plane \
	--additional-properties=java8=true,library=spring-boot
```

Common pitfalls
- Generating code directly into main source directories (use `build/generated` or separate module).
- Relying on default generator templates — customize to align with project conventions.
- Missing example fixtures — use `examples/` to validate schemas.

PR reviewer checklist
- Spectral lint passes and any custom rules satisfied
- Example requests/responses validate against the schema
- Security schemes and scopes documented and applied to operations
- Generated code compiles and basic smoke tests included or referenced

Training resources
- Spectral linting: https://meta.stoplight.io/docs/spectral
- OpenAPI Generator: https://openapi-generator.tech/docs/usage
- Contract-first API design patterns (internal or general articles)

Success criteria
- OpenAPI lints clean in CI with project ruleset
- Generated scaffold compiles and basic smoke tests pass in CI
- Contract-change checklist attached to PR for any non-trivial changes