A linter is a static-analysis tool that examines an API definition for design errors, authoring problems, stylistic inconsistencies, and possible improvements. API linting applies this practice to documents such as OpenAPI descriptions, helping teams enforce design guidelines while keeping attention on consumer needs. section 18.0 section 18.1
An API linter can:
- Detect inconsistent property naming, missing pagination parameters, undefined security scopes, duplicated path parameters, and inline schemas. section 18.1.1
- Apply API design guidelines automatically, including patterns intended to improve consistency, usability, security, efficiency, and extensibility. section 18.1 section 18.1.2
- Run in an IDE, OpenAPI editor, terminal, or CI/CD pipeline, regardless of how the OpenAPI document was created. section 18.1.1
- Report problem locations and descriptions so designers can correct avoidable issues before they require breaking changes. section 18.1.1
Catching design problems before implementation
Suppose an OpenAPI document describes a product search operation. A linter can flag inconsistent property casing, missing pagination parameters, and undefined authorization scopes, while also identifying duplicated path parameters or an inline request schema. Designers can fix these issues before consumer teams build against the API. section 18.1.1 section 16.3.1
Linting works best as the automation of reasoned API design guidelines, not as an independent collection of arbitrary rules. It catches details and recurring patterns, but it cannot decide whether an operation meets consumer needs or understand every subject-matter and architectural concern. Spectral supports customizable, reusable, shareable rules and targeted exceptions; other linters can serve OpenAPI, AsyncAPI, gRPC, or GraphQL APIs. section 18.1.2 section 18.2.3
Figure 18.1 We can use an API linter to apply our guidelines seamlessly. Linting can help us with API design and OpenAPI authoring.
Use the workflow view to connect automated guideline checks with API design and OpenAPI authoring. section 18.1
