Documenting RESTful APIs with Spring REST Docs and 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 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.

Transcript

1. Mathias Düsterhöft @zaddo DOCUMENTING RESTFUL APIS WITH SPRING REST DOCS AND RAML
4. Why Spring REST Docs? •Takes a test-driven approach which guarantees accuracy •Uses Asciidoctor •Works with Spring MVC Test
5. Spring REST Docs demo
6. Towards a public API documentation
7. Bring Tech Writers in •Tech writers should not have to edit descriptions in tests .andDo(document("product-get", responseFields( fieldWithPath("name") .description("The name of the product."), fieldWithPath("price") .description("The price of the product.") ) ));
8. Bring Tech Writers in .andDo(document("cart-create-payment", requestFields( fieldWithPath("returnUri", "createPayment.returnUri"), fieldWithPath("cancelUri", "createPayment.cancelUri")), responseFields( fieldWithPath("approvalUri", "createPayment.approvalUri")))); createPayment.returnUri: description: The redirect URI after successful payment authorization. createPayment.cancelUri: description: The redirect URI if the payment authorization was not… createPayment.approvalUri: description: The URI used to approve the payment. The client has to…
9. Consistent Test Data •In documenting tests, we use a test data catalog defined by TechWriting
10. Aggregate Documentation •One repository that composes all public documentation from the relevant microservices
11. Aggregate Documentation
12. First achievements
13. First Achievements •Static API documentation available on our developer portal •Good starting point to work with partners
14. h We want to go further
15. A machine readable API description? •AsciiDoc as a markup language is hard to process •It is hard to get any further than static HTML •A machine readable format is what we need
17. RAML by Example #%RAML 1.0 title: Hello world # required title /greeting: # optional resource get: # HTTP method declaration responses: # declare a response 200: # HTTP status code body: # declare content of response application/json: # media type # structural definition of a response (schema or type) type: object properties: message: string example: # example how a response looks like message: "Hello world"
18. Introducing restdocs-raml •We built restdocs-raml •To keep the benefits of Spring REST Docs •To get a RAML description of our API
20. restdocs-raml demo
21. Conclusion •Adding restdocs-raml to an existing project is easy •A RAML representation of an API opens a lot of new possibilities •Leverage the tools available in the RAML ecosystem
22. Reference • Sample project • https://github.com/mduesterhoeft/spring-restdocs-raml-talk • restdocs-raml • https://github.com/ePages-de/restdocs-raml
23. Mathias Düsterhöft @zaddo @epagesdevs https://gitter.im/restdocs-raml/restdocs-raml THANKS!