About openapi validator
Check an OpenAPI or Swagger file for missing fields, duplicate operation IDs and bad references.
Common errors
- A $ref pointing to a component that does not exist.
- Duplicate operationId values.
- Path parameters in the URL that are not declared.
- Missing response descriptions.
A worked example
A specification where two operations share the operationId getUser, or a $ref points to #/components/schemas/Usr (a typo), is flagged with the location of the problem. Fixing these before generating clients saves confusing errors later.
Other common findings
- Path parameters used in a path but not defined.
- Responses without a description.
- Missing security definitions for protected endpoints.
Linting for style
Beyond correctness, linters such as Spectral can enforce rules like descriptions on every operation and consistent naming. Add one to your pipeline once the file is valid.
Fix in order
Fix reference and structure errors first, because they often cause several other warnings to appear at the same time.
