Requiring that all operational parameters descriptions meets the policy standards.
Parameter Descriptions
Rules
OpenAPI Components Parameters Description Error
Having a parameters description provides more depth to what a parameter does and will be displayed via documentation, and other tooling used across the API lifecycle
OpenAPI Components Parameters Description Info
Having a parameters description provides more depth to what a parameter does and will be displayed via documentation, and other tooling used across the API lifecycle
OpenAPI Components Parameters Description Length Error
Limiting the length of parameters description forces us to be more concise in how we describe each parameter, while keeping our documentation and other ways descriptions show up in discovery and po...
Strategies
API Parameters Are Well-Defined and Consistent
All API parameters must have clear names, descriptions, types, and constraints following consistent casing and naming conventions, with reusable parameters centralized in OpenAPI components to redu...
Operations Must Be Useful and Consistent
All individual API operations must be useful and follow consistent Internet, industry, and enterprise standards, providing a simple and relevant HTTP API operation that does one thing and does it w...
Lifecycle
design_services Design Design
Design is where the human experience of an API is won or lost. I work design-first, shaping the paths, schema, errors, and naming in the contract before development begins, so that consistency is b...
menu_book Documentation Beta
Documentation is the API for humans. I generate reference docs from the definition and surround them with the guides, examples, and getting-started material that turn a spec into understanding. Doc...
