Documenting RESTful APIs with Spring REST Docs and RAML by Mathias Düsterhöft @ Spring I/O 2018
Spring I/O 2018 - Barcelona, 24-25 May
Slides: https://speakerdeck.com/mduesterhoeft...
Spring REST Docs is a great tool to produce documentation for your RESTful services that is accurate and readable.
It offers support for AsciiDoc and Markdown. This is great for generating simple HTML-based documentation.
But what if your REST API is a big part of the product you offer? Then static HTML is probably not enough and you have to offer a richer experience for your API consumers.
In this case, Asciidoctor and Markdown are not ideal - they are markup languages and hard to process further. You are better off with a technical representation of your API - something like RAML.
The RESTful API Modeling Language (RAML) is a YAML-based language to describe RESTful APIs. Having a RAML representation of your API opens a lot of possibilities. There is a rich ecosystem around it, and of course, you can write your own tools to process your API description.
Let's look at how restdocs-raml (https://github.com/ePages-de/restdocs...) can help us to add RAML support to String REST Docs. I will motivate why we built restdocs-raml and give an introduction to the project and RAML in general. We will take an existing project that uses Spring REST Docs and apply restdocs-raml to it. Once we have a RAML description of our API, I will showcase the possibilities that RAML gives you out of the box.
Watch video Documenting RESTful APIs with Spring REST Docs and RAML by Mathias Düsterhöft @ Spring I/O 2018 online, duration hours minute second in high quality that is uploaded to the channel Spring I/O 03 July 2018. Share the link to the video on social media so that your subscribers and friends will also watch this video. This video clip has been viewed 2,854 times and liked it 33 visitors.
