Documenting RESTful APIs
summary
Argues that Swagger can mislead when documenting Spring MVC—Swagger lacks Hypermedia support and it often misinterprets response types—then demos a working pipeline that builds a simple notes API with Spring Data REST, exercises it with MockMvc, and generates test-driven snippets with Spring REST Docs (curl examples, HTTP responses, link and field tables). Uses Asciidoctor and Gradle continuous build plus live-reload to produce HTML docs as part of CI, ensuring examples are accurate because tests must pass.
AI-written summary · about
chapters (10)
- 0:00Introduction to API documentation
- 1:12REST maturity model explained
- 6:47Designing consistent REST APIs
- 11:48Essential API documentation elements
- 17:26What not to document in APIs
- 19:51Bad API documentation examples
- 23:44Good API documentation examples
- 26:52Tools for documenting Spring APIs
- 40:19Introducing Spring REST Docs
- 51:58Live coding with Spring REST Docs
related talks
57mDocumenting RESTful APIs with Spring REST Docs
52mTest-driven documentation with Spring REST Docs
33mDocumenting REST APIs with Swagger
26mDocumenting Your API Effectively: a Complete Tour of Spring-doc
50mSpring REST Docs: Documentation From Tests, Not the Other Way Around
50mUsing Spring with OpenAPI
01h 34mDesigning a REST-ful API using Spring 3
46mJUnit, RESTDocs, Asciidoctor and Maven to document your APIs