Documenting RESTful APIs with Spring REST Docs

on YouTube ↗57m

" summary

A test-driven workflow that uses Spring REST Docs plus Asciidoctor to generate real request/response snippets from integration tests, hooked into Gradle or Maven, produces HTML/PDF docs and pushes to GitHub Pages. Example app: a greetings API with POST/GET endpoints, generated curl/postman examples, and reusable snippet templates; tests fail when fields change so documentation stays accurate. Works with WebFlux, Ratpack and REST-assured, and integrates with Postman or curl.

AI-written summary · about

" chapters (15)

1. 0:00Introduction to talk
2. 3:46Understanding API documentation needs
3. 7:06Common API documentation challenges
4. 13:54Documentation tooling landscape
5. 19:37Problems with Swagger
6. 25:43Test-driven documentation concept
7. 28:54Spring REST Docs overview
8. 31:53Setting up Spring REST Docs
9. 35:43Writing tests with WebTestClient
10. 40:49Generating documentation snippets
11. 45:55Integrating snippets into docs
12. 49:37Customizing documentation output
13. 52:10Publishing documentation
14. 54:37Using REST Docs with other frameworks
15. 55:45Conclusion and resources

" related talks

• 52mTest-driven documentation with Spring REST DocsAndy Wilkinson · Spring I/O 2016
• 01h 23mDocumenting RESTful APIsAndy Wilkinson · SpringOne2GX 2015
• 50mSpring REST Docs: Documentation From Tests, Not the Other Way AroundYan Ashenkampf · TestDriven Conf 2022
• 41mIntroducing Spring Auto REST DocsFlorian Benz · Spring I/O 2017
• 26mDocumenting Your API Effectively: a Complete Tour of Spring-docHugo Caupert · Voxxed Days Luxembourg 2023
• 46mJUnit, RESTDocs, Asciidoctor and Maven to document your APIsPetar Tahchiev · JavaDay Ukraine 2017
• 51mDocumenting RESTful APIs with Spring REST Docs and RAMLMathias Düsterhöft · Spring I/O 2018
• 35mBringing together OpenAPI 3 and Spring BootBadr Nasslahsen · Spring I/O Bridge 2020