REST API documentation

on YouTube ↗41m

" summary

Covers how to produce and maintain REST API documentation that stays current by keeping docs close to code. Discusses the problem of stale documentation when teams separate backend and frontend or expose APIs to third parties, and argues against storing docs in Google Docs/Markdown/reStructuredText alone, advocating embedding documentation with the codebase.

AI-written summary · about

" chapters (14)

1. 0:00Introduction
2. 1:33What is an API
3. 2:39REST requirements
4. 5:53REST API methods
5. 8:03API documentation problems
6. 9:45Documentation tools
7. 11:56OpenAPI and Swagger
8. 13:25Top-down vs bottom-up
9. 17:00Swagger tool
10. 28:01Code generation from spec
11. 33:04Swagger features and alternatives
12. 34:49Summary and recommendations
13. 35:52Call to document APIs
14. 36:14Q&A

" related talks

• 35mDocumenting APIs: new era, same craftJavier Rubio · Write the Docs Berlin 2026
• 26mDocumenting Your API Effectively: a Complete Tour of Spring-docHugo Caupert · Voxxed Days Luxembourg 2023
• 50mSpring REST Docs: Documentation From Tests, Not the Other Way AroundYan Ashenkampf · TestDriven Conf 2022
• 26mA sensible API Document Management guideVanjikumaran Sivajothy · Apidays LIVE Paris 2020
• 25mThe link between technical documentation and developer engagementDheeraj Nayal · apidays India 2021
• 38mThe Secret to Brewing up a Good APIDavid Dymko · Open Source Summit + Embedded Linux Conference + OSPOCon 2021
• 57mDocumenting RESTful APIs with Spring REST DocsJennifer Strater · SpringOne Platform 2017
• 30mSo You Need to Document an API?Allison Reinheimer Moore · Write the Docs North America 2016