TopolearnAutomated checks keep a growing API description consistent and useful.
Three tool types belong in every OpenAPI workflow.
Validation and linting. Validation checks the document is legal OpenAPI. Linting enforces your style guide on top: every operation has an operationId and a 4XX response, names are kebab-case paths and camelCase properties, no unused components, descriptions present.
- Redocly CLI:
redocly lint openapi.yamlwith configurable rules inredocly.yaml, plusbundleandsplitfor multi-file documents. - Spectral (Stoplight): rulesets written in YAML with JSONPath selectors;
spectral:oasis the built-in set, and organisations publish their own.
Run linting in CI on every pull request that touches the API.
Reference documentation. Swagger UI, Redoc and Scalar render the document as browsable docs with request consoles. Descriptions support CommonMark Markdown, so write real explanations there, and use tags to structure the navigation.
Mock servers. Prism serves responses derived from your examples and schemas: prism mock openapi.yaml. Frontend and partner teams can build against the contract before the backend exists. Prism can also run as a validation proxy in front of a real server and report requests or responses that violate the contract.
Example
# Validate + lint with Redocly
npx @redocly/cli lint openapi.yaml
# validates the document and applies the recommended rules
# Bundle a multi-file description into one file for publishing
npx @redocly/cli bundle openapi.yaml -o dist/openapi.yaml
# Lint with Spectral (.spectral.yaml: extends: ["spectral:oas"])
npx @stoplight/spectral-cli lint openapi.yaml
# Mock server from examples and schemas
npx @stoplight/prism-cli mock openapi.yaml
curl -s http://127.0.0.1:4010/books/123
# -> example (or generated) Book JSON
# Validation proxy in front of the real API
npx @stoplight/prism-cli proxy openapi.yaml http://localhost:8000Remember
- Validate for correctness, lint for your style guide
- Run lint in CI on every API change
- Swagger UI, Redoc and Scalar render reference docs
- Prism mocks the API and validates real traffic as a proxy
Watch out for
- Mocks returning schema-generated junk because the document has no realistic examples.