Documenting APIs: new era, same craft
summary
API docs need to be close to the code: generate an OpenAPI file from tests that go red auto-generate spec or from annotations so docs ship with every deploy and stay current. OpenAPI still leaves gaps — authentication, errors, pagination, rate limits, versioning — so add explicit guides, a sandbox, migration guides and a changelog. Tooling options include Swagger/Redoc, Postman/Insomnia or DIY with Redocusaurus; use OpenAPI, extensions, Arazzo and AI to write maintenance tests, not whole specs.
AI-written summary · about
chapters (19)
- 0:00API documentation intro
- 1:08API docs history
- 3:36OpenAPI for REST contracts
- 7:52API docs tool fragmentation
- 9:17Choosing tools by workflow
- 10:19Docs as code ownership
- 11:48Engineering API docs
- 17:56AI in API documentation
- 19:03API docs as product
- 22:59User personas and guides
- 24:48Workflow-focused docs
- 25:56AI as API docs audience
- 27:40Reducing token waste
- 28:02Collaboration in docs
- 28:46Q&A: Human-centric APIs
- 30:12Q&A: Specs from traffic
- 31:17Q&A: API docs future
- 32:24Q&A: Software identity crisis
- 33:09Q&A: Docs as code responsibility
related talks
35mOpenAPI for Documentarians
19mSecure and accelerate APIs' lifecycle with the OpenAPI specification
38mThe Secret to Brewing up a Good API
21mLet there be docs!
27mGetting developers hooked on your API
24mBuilding an Accessible API Spec with Traditional Engineering Teams
26mA sensible API Document Management guide
21mDesigning APIs with OpenAPI: Build the Right APIs the Right Way.