Documenting RESTful APIs with Spring REST Docs and RAML

on YouTube ↗51m

" summary

Spring REST Docs plus restdocs-raml turns test-driven snippets into a machine-readable RAML API (API.raml) and JSON Schemas, extracting request/response fields, links and examples from MockMVC tests and failing builds when documentation and payload diverge. CI collects per-service snippets into a single RAML for the public developer portal. Outputs feed raml2html, the API Console, and converters (APIMatic → Postman), enabling interactive docs and usable artifacts from existing tests. test-driven snippets fail tests on mismatch restdocs-raml generates API.raml and JSON Schema raml2html and API Console produce interactive docs

AI-written summary · about

" chapters (5)

1. 0:00Start
2. 2:31Why Spring REST Docs?
3. 18:47Aggregate Documentation
4. 22:22A machine readable API description?
5. 44:38Conclusion

" related talks

• 30mRAML - Specification to manage the API lifecycleFátima Casaú · Spring I/O 2016
• 57mDocumenting RESTful APIs with Spring REST DocsJennifer Strater · SpringOne Platform 2017
• 52mTest-driven documentation with Spring REST DocsAndy Wilkinson · Spring I/O 2016
• 50mSpring REST Docs: Documentation From Tests, Not the Other Way AroundYan Ashenkampf · TestDriven Conf 2022
• 01h 23mDocumenting RESTful APIsAndy Wilkinson · SpringOne2GX 2015
• 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