How to produce RAML with Spring REST Docs using restdocs-raml
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 creating simple HTML-based API documentation that combines hand-written content with generated snippets.
At ePages we have been using Spring REST Docs from the start in our new ecommerce backend. We love its test-driven approach to document a REST API. It helps us to make sure that the documentation is always up-to date. New fields added to a resource are never left undocumented. Changed and removed fields will not leave the documentation stale. This is awesome.
But Asciidoc and HTML do not allow us to go any further than statically generated HTML. In the long run we want to make our public API documentation more approachable and appealing by adding interactive elements. To achieve this we needed an API description that we can process further. RAML seemed like a good fit. We already had experience with RAML so we went for it.
At the same time we did not want to loose the benefits that Spring REST Docs gives. So we came up with restdocs-raml, an extension to Spring REST Docs that adds RAML support. The idea is to emit RAML fragments instead of, or in addition to Asciidoc from the tests that document the API.
Spring REST Docs
When integration testing the REST API in a Spring-based project you usually use the Spring MVC Test Framework.
Testing an endpoint can look like this:
Spring REST Docs nicely integrates into this framework and makes it easy to add documentation:
In the example above the test will fail if not all response fields are documented or if a documented field does not exist in the response. Thus, we can remove the andExpect assertions for existence of fields in the payload. This is now asserted by Spring REST Docs.
The document method will emit so-called snippets containing Asciidoc files.
Introducing restdocs-raml
Let’s now look at how to get Spring REST Docs to emit RAML.
The easiest way to do this is to just exchange the static import of the static document method. Instead of using org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document we go for com.epages.restdocs.raml.RamlDocumentation.document.
This will transparently add the RamlResourceSnippet equipped with all the information from the available snippets. The remaining snippets will still be executed.
If you are starting from scratch and do not have to migrate existing tests we suggest to use the RamlResourceSnippet directly.
Both variants will result in similar RAML fragment int the output directory:
The field descriptors given in the responseFields are used to generate a JsonSchema for the response. The recorded response is added as an example.
These RAML fragments are picked up by the restdocs-raml-gradle-plugin and are transformed into a RAML file describing all the documented resources of the project.
The resulting top-level RAML file just lists the top-level resources and includes fragments describing these resources:
The fragments contain the full description of the corresponding resources.
Having a RAML description of an API opens a huge amount of possibilities just by leveraging the richness of the RAML ecosystem. We can easily generate a HTML representation using raml2html or create an interactive API playground using api-console-cli. The additional value of a technical API description is significant.
We plan to use the RAML description of our API to generate a public API documentation that allows the reader to interact with the API while reading the documentation.
For further details, please have a look at the github repo of restdocs-raml. The readme and the sample application contain useful information to try out restdocs-raml. And in case you give it a try, please drop us a line in the gitter chat and let us know what you think.
