API documentation is the most common way to “see” an API, making it one of the most critical aspects of how API producers and consumers engage. Out of date, incomplete, and hard to find documentation is the number one challenge for API consumers, and is the most important place that API producers can invest. Documentation should be generated from OpenAPI or AsyncAPI, with the finer details like summaries, descriptions, examples, and other elements included, making the documentation as rich and educaitonal as possible.
Documentation historically lives via a developer portal, but increasingly is being made portable and baked into the expanding developer experience API providers are crafting to stand out and support their communities. While referene documentation for your API is till the baseline, increasingly API providers are publishing onboarding, capability, workflow, and other types of tests, while also ensuring mocks, tests, and other building blocks of API operations are as documented as they possibly can.
