Documenting RESTful APIs with Spring REST Docs and RAML

by Mathias Düsterhöft

Slide 1

Slide 1 text

Mathias Düsterhöft @zaddo DOCUMENTING RESTFUL APIS WITH SPRING REST DOCS AND RAML

Slide 2

Slide 2 text

No content

Slide 3

Slide 3 text

No content

Slide 4

Slide 4 text

Why Spring REST Docs? •Takes a test-driven approach which guarantees accuracy •Uses Asciidoctor •Works with Spring MVC Test

Slide 5

Slide 5 text

Spring REST Docs demo

Slide 6

Slide 6 text

Towards a public API documentation

Slide 7

Slide 7 text

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.") ) ));

Slide 8

Slide 8 text

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…

Slide 9

Slide 9 text

Consistent Test Data •In documenting tests, we use a test data catalog deﬁned by TechWriting

Slide 10

Slide 10 text

Aggregate Documentation •One repository that composes all public documentation from the relevant microservices

Slide 11

Slide 11 text

Aggregate Documentation

Slide 12

Slide 12 text

First achievements

Slide 13

Slide 13 text

First Achievements •Static API documentation available on our developer portal •Good starting point to work with partners

Slide 14

Slide 14 text

h We want to go further

Slide 15

Slide 15 text

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

Slide 16

Slide 16 text

No content

Slide 17

Slide 17 text

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"

Slide 18

Slide 18 text

Introducing restdocs-raml •We built restdocs-raml •To keep the beneﬁts of Spring REST Docs •To get a RAML description of our API

Slide 19

Slide 19 text

No content

Slide 20

Slide 20 text

restdocs-raml demo

Slide 21

Slide 21 text

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

Slide 22

Slide 22 text

Reference • Sample project • https://github.com/mduesterhoeft/spring-restdocs-raml-talk • restdocs-raml • https://github.com/ePages-de/restdocs-raml

Slide 23

Slide 23 text

Mathias Düsterhöft @zaddo @epagesdevs https://gitter.im/restdocs-raml/restdocs-raml THANKS!