When developing a REST web service, it becomes crucial having a documentation that is accurate, up-to-date and well-structured. There are many tools nowadays that can be used in projects and that will help writing a documentation that will meet the above-mentioned needs. But some of them prove to be just a little more handy in web service development. Spring REST Docs are already known as a tool that has a different approach. But not even its benefits meet all needs a developer has. This especially refers to the cases when there is a project consisted of several microservices. This presentation will show how RAML can be used in order to produce documentation that takes into account all benefits of Spring REST Docs while also introducing a lot of possibilities out of the box. A simple example will be used in order to demonstrate this approach and some features.

1. RAML BASED
REST API
DOCUMENTATIO
N
Author: Matea Pejčinović
Contact: matea.pejcinovic@gmail.com

2. Overview ■ Why documentation matters?
■ Approaches in documenting REST
APIs in Java
■ Spring Rest Docs
■ What is RAML?
■ RAML support for Spring REST
Docs
■ Demo
■ Handy tools
RAML Based REST API docs 2

3. Why documentation matters?
■ When connecting to another API, a
documentation becomes crucial
■ When another developer starts developing some
new features, a documentation would be the
first place to look for information
■ Outdated documentation has a big impact on
the partners and clients
RAML Based REST API docs 3

4. REST API Documentation
Generators for Java
■ Swagger
– A complete framework for describing, producing, consuming and visualizing
RESTful web services
– Free to use
■ RAML (RESTful API Modeling Language)
– Having a RAML file for description of the API, it can be consumed by different
platforms to parse and display information
– Free to use
■ Spring REST Docs
– Generates documentation that is bothe accurate and readable
– Documentation is generated using tests
RAML Based REST API docs 4

5. Spring REST Docs
■ It is Spring REST annotation aware
■ Test-drven approach
■ Combination of a hand-written documentation and
auto-generated snippets
■ Description of resources
■ Documentation is:
– Accurate
– Concise
– Well-structured
RAML Based REST API docs 5

6. RAML support for Spring REST Docs
■ Developed by ePages
■ Keeps all benefits from Spring REST Docs, but adds them
■ Why RAML?
– Unique set of strings
– TDD approach
– Unique document for several microservices
RAML Based REST API docs 6

7. RAML
■ RESTful API Modeling language
■ Machine readable API that is human friendly
■ Many different tools for RAML
RAML Based REST API docs 7

8. DEMO
RAML Based REST API docs 8

9. Handy tools
■ Many tools from npm (Mulesoft)
■ raml2html
■ apiconsole
■ ApiMatic
■ Postman
RAML Based REST API docs 9

10. Questions?
RAML Based REST API docs 10