API linting automatically analyzes an API description, typically an OpenAPI document, for design and authoring problems. It applies API design guidelines consistently, supporting user-friendliness, security, efficiency, extensibility, and maintainability while leaving consumer-focused design decisions to people. section 18.0 section 18.1
A linter can help teams:
- Detect inconsistent property naming, missing pagination parameters, undefined security scopes, duplicated path parameters, and unclear inline schemas. section 18.1.1
- Run checks in an IDE, OpenAPI editor, terminal, or CI/CD pipeline before avoidable errors become breaking changes. section 18.1.1
- Reduce guideline memorization without replacing analysis of whether an API actually meets consumer needs. section 18.1.2
Checking a product search operation
A lint rule can flag a search operation that lacks pagination or uses inconsistent parameter names such as cursor versus next and pageSize versus limit. It can also catch a property such as Account when the guideline requires account, preventing a later breaking rename. section 18.0 section 18.1.1
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 this overview to see how an API linter applies guidelines to both API design and OpenAPI authoring. section 18.1
