An Alternative View on OpenAPI Docs, Start Finally Doing it Right!
summary
Proposes generating OpenAPI from per-route OPTIONS responses so each HTTP method handler emits a tiny YAML fragment, assembling larger specs with a YAML composer keyed from the routing table. Uses docstring-driven YAML fragments inside handlers as the canonical source, with CI pulling only changed fragments rather than a massive monolith file. Claims this cuts generation time, makes tests request-specific, speeds pipelines and makes specs human-readable by design. route-level source of truth
AI-written summary · about
chapters (13)
- 0:00Introduction
- 1:56OpenAPI documentation matters
- 3:43Alternatives and limitations
- 5:07Current OpenAPI problems
- 7:17OpenAPI usage challenges
- 9:06Cost of large OpenAPI files
- 12:25Split OpenAPI into fragments
- 13:29Single-endpoint documentation
- 15:38YAML pipeline for multi-service
- 16:43Docstrings for OpenAPI generation
- 17:28Live demonstration
- 20:04OpenAPI specification proposal
- 20:47Summary
related talks
35mOpenAPI for Documentarians
21mLet there be docs!
38mThe Secret to Brewing up a Good API
47mContract-Driven API Development with OpenAPI Specification
22mBeyond the Spec: Making OpenAPI More Human
24mBuilding an Accessible API Spec with Traditional Engineering Teams
38mZen And The Art Of Automanually Creating API Documentation - An Inquiry Into Process
35mAPI-First! Contract-First! Make API development great again!