OpenAPI for Documentarians
summary
Explains concrete practices not platitudes: shows a folded-yaml visualization, recommends editors and plugins (VS Code, linting, CI), names tooling sources like openapi.tools and vendor extensions such as Redocly and overlays/decorators to augment generated specs, and emphasizes examples and reusable components and refs with named response examples. Cites a surprising stat (55% cite lack of documentation as the main API blocker) and stresses governance, measurable docs metrics, and how to retrofit specs.
AI-written summary · about
chapters (9)
- 0:00OpenAPI for documentarians
- 3:13Why OpenAPI matters
- 8:51OpenAPI structure visually
- 14:53Paths and endpoints
- 20:57Power of examples in schemas
- 25:28Choosing OpenAPI tools
- 27:58API governance checks
- 31:49Proving documentation impact
- 32:52Resources and closing
related talks
35mDocumenting APIs: new era, same craft
22mBeyond the Spec: Making OpenAPI More Human
27mGetting developers hooked on your API
21mLet there be docs!
38mThe Secret to Brewing up a Good API
51mWriting the Darn Docs
38mZen And The Art Of Automanually Creating API Documentation - An Inquiry Into Process
24mBuilding an Accessible API Spec with Traditional Engineering Teams