How do I validate OpenAPI docs before publishing?

To validate OpenAPI docs before publishing, use a mix of schema validation, linting, and contract checks in your CI pipeline.

1) Validate the OpenAPI document structure

Check that the file is valid YAML/JSON and conforms to the OpenAPI version you’re using.

Tools:

• Swagger Editor / Swagger CLI
• Spectral
• OpenAPI Generator validate
• Redocly CLI

Examples:

npx swagger-cli validate openapi.yaml

npx @redocly/cli lint openapi.yaml

npx spectral lint openapi.yaml

2) Lint for style and API design issues

Linting catches:

• missing descriptions
• inconsistent naming
• invalid or unclear status codes
• missing response schemas
• bad parameter definitions
• unused components

Good choice: Spectral with custom rules.

Example:

npx spectral lint openapi.yaml

3) Validate references

Make sure $ref pointers resolve correctly:

• missing files
• broken component references
• circular references if unsupported by tooling

Tools like swagger-cli and Redocly do this well.

4) Run contract tests against your implementation

If the API already exists, validate that the OpenAPI spec matches the server behavior:

• request/response status codes
• response bodies
• required fields
• content types

Tools:

• Dredd
• Schemathesis
• OpenAPI Enforcer
• Prism for mock validation

Example with Schemathesis:

schemathesis run openapi.yaml --base-url http://localhost:8000

5) Validate examples

Check that:

• request examples match schema
• response examples match schema
• enum values are valid
• formats are correct

Some linters can validate examples too.

6) Automate in CI

Add validation steps before merge/publish:

npx swagger-cli validate openapi.yaml
npx spectral lint openapi.yaml
schemathesis run openapi.yaml --base-url http://localhost:8000

Recommended pipeline

A practical setup is:

1. Parse/validate the spec
2. Lint with Spectral/Redocly
3. Resolve refs
4. Run contract tests
5. Fail the build on any error

Quick recommendation

If you want one strong tool to start with:

• Redocly CLI for validation + linting
• Spectral if you want customizable rules
• Schemathesis if you also want runtime contract testing

If you want, I can give you a ready-to-use GitHub Actions workflow or CI script for OpenAPI validation.