All OpenAPI definitions must have complete info objects including title, description, version, contact information, license, and terms of service, providing both humans and machines with the context needed to understand, evaluate, and properly use each API.
API Info and Metadata Is Complete and Accurate
Policies
Title of APIs
The title in your OpenAPI is the name that shows up everywhere -- in docs, catalogs, and code generation. Getting the casing, length, and clarity right here sets the tone for everything.
Description of APIs
The description in your OpenAPI info block is prime real estate. This is where you tell consumers what the API is about in a way that makes them want to keep reading.
Version of APIs
Version information in your OpenAPI tells consumers which release they are looking at. Whether you use semantic versioning or date-based, having it in the spec is how you communicate where things s...
Contact Information for APIs
Contact information in your OpenAPI info section tells consumers who to reach out to. It is a small detail that makes a big difference when someone is stuck or has a question.
License for APIs
Including a license in your OpenAPI info section makes the legal terms explicit. I see way too many APIs where consumers have no idea what they are legally allowed to do.
Terms of Service for APIs
Terms of service linked from your OpenAPI info give consumers the legal context they need. Making this part of the technical contract means it travels everywhere the spec goes.
OpenAPI Version
Using the latest version of OpenAPI keeps your specs aligned with what tooling supports. Falling behind on spec versions means missing out on features and governance capabilities.
OpenAPI Tags
Tags at the OpenAPI level organize your API into logical groups. They need names, descriptions, and consistent casing to actually serve their purpose in documentation and discovery.
Experiences
Discovery
Discovery is the dark matter of the API landscape. Teams build APIs that already exist somewhere else, and consumers can't find the APIs they need. Without a catalog and proper metadata, you're jus...
Onboarding
I see teams dealing with massive friction during onboarding. If a consumer can't get from zero to their first successful API call in minutes, you've already lost them. Getting started guides, sandb...
Quality
I see the quality of APIs eroding across the landscape. Teams ship fast and never look back, but consumers feel every rough edge, every missing example, every inconsistent response. Quality is what...
Consistency
When I look across the API landscape, consistency is one of the biggest challenges I see. Every team does things differently, and the surface area of inconsistency just grows until governance becom...
Communication
I struggle with how little communication happens between the teams producing APIs and the people consuming them. Blogs, changelogs, roadmaps -- these are building blocks that most teams just skip, ...