Documenting RESTful APIs with Spring REST Docs and RAML
Mathias Düsterhöft at Spring I/O 2018
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-raml) 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.
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-raml) 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.