Let there be docs!
summary
Argues for a documentation-first workflow that writes an OpenAPI spec before code, uses JSON Schema for validations, and catches misunderstandings early — example: designing a Twitter-like feed in the spec prevented building the wrong feature. Recommends OpenAPI 3.1, linters like spectral, mock servers (Prism) and UIs (Swagger UI) so front end starts sooner, and shows tests that validate requests and responses against the spec using the schuma gem (OpenAPI+JSON Schema support), first release available and working in CI.
AI-written summary · about
chapters (10)
- 0:00Introduction and humor
- 2:52Why documentation matters
- 5:45Four API documentation approaches
- 7:33Documentation first explained
- 8:42OpenAPI specification demo
- 12:56Iterating on documentation
- 13:39Testing and implementing API
- 16:57Introducing Schuma gem
- 17:38Tips for adopting documentation first
- 19:48Recap and resources
related talks
35mDocumenting APIs: new era, same craft
35mOpenAPI for Documentarians
30mOne Spec to Rule them all - OpenAPI in Action
27mGetting developers hooked on your API
24mBuilding an Accessible API Spec with Traditional Engineering Teams
22mBeyond the Spec: Making OpenAPI More Human
51mWriting the Darn Docs
38mZen And The Art Of Automanually Creating API Documentation - An Inquiry Into Process