Struggling to document your APIs? Still using a wiki page to do it? Watch this presentation and learn the secrets of documenting REST APIs! One of the secrets to a successful Microservices application is the quality of its APIs - so using a decent tool to help develop them is essential; without the right tool, producing APIs can become as tedious as reading through a dump file. This presentation introduces a selection of opensource tools intended to help with not just documenting APIs but designing and testing them as well. Tools covered will include: Swagger, RAML, Spring RestDocs and Apiary.

1. Zen and the Art of REST API
documentation
1
µCon London - Nov, 2015

2. About me
2
Steve Judd - Lead Consultant
OpenCredo - an Open Source software consultancy

3. 3
Agenda

4. Completeness
URI
Request/Response objects
Status codes used
Headers
Consistency
Extra features
Client & Server mocking
Testing
Code generation
4
WHY

5. 5
WHICH
Swagger
RAML
API Blueprint

6. 6
BACKGROUND
Swagger RAML API Blueprint
Spec format YAML, JSON YAML Markdown
Backed by Reverb, SmartBear
MuleSoft, Intuit,
Cisco…
Apiary
First appeared 2011 2013 2013
Commercial
offering
Yes (via swagger.io) No Yes (via apiary.io)
Popularity
Github: 393
StackOverflow: ~2900
GitHub: 140
StackOverflow: ~260
GitHub: 58
StackOverflow: ~300

7. 7
SPEC COMPARISON
Swagger RAML API Blueprint
REST modelling
All support: resources, methods, status codes, query, path &
header params
HATEOAS ✘ ✘ ✘
Authentication ✔ ✔ ✘
Versioning ✔ ✔ ✘
Example
representations ✔ ✔ ✔

8. 8
TOOLING COMPARISON
Swagger RAML API Blueprint
Editor ✔✔ ✔✔ ✔
Interactive API
explorer ✔✔ ✔ ✔
Mocking tools ✔✔ ✔✔ ✔✔
Language support
Java, PHP, Node/JS,
Ruby, Clojure, C#, Scala,
Python, Go, .Net, Perl
Java, PHP, Node/JS,
Ruby, Python, .Net
Java, Node/JS, Ruby, .Net
Testing support ✔ ✔✔ ✔✔
Code generation ✔✔✔ ✔ ✘
Publishing tools ✔✔✔ ✔ ✔

9. 9
The Editors...

10. 10
Swagger Editor

11. 11
API Designer (RAML)

12. 12
Apiary (API Blueprint)

13. Swagger
swagger-test (Node.js)
assertj-swagger (Java/Maven)
RAML
abao (Node.js)
raml-tester (Java/Maven)
API Blueprint
Dredd (Ruby, Python, Node.js, PHP)
13
Contract verification

14. Take 1 top-down
API spec (written in
Swagger)
And 1 bottom-up
API spec
(produced using
SpringFox or JAX-
RS Swagger)
And assert that they
are equal
assertj-swagger
14

15. •abao uses any
examples defined
in the API spec
file as test data.
•You can also
define extra test
data.
•Run abao against
a running instance
of your
implementation
abao
15

16. Swagger
swagger2Markup: Spec -> AsciiDoc or
Markdown
various Spec -> HTML projects
RAML
raml2html: Spec -> HTML
raml2md: Spec -> Markdown
API Blueprint
Aglio: Spec -> HTML
16
Publishing

17. 17
Summary
Swagger & RAML mostly equal and
ahead of API Blueprint
Swagger seems more popular
Swagger probably has more
support for Java projects
RAML probably has more support
for Node.js projects
Either is a good choice

18. Thank you and any questions?
http://www.opencredo.com/blog
@OpenCredo
@cyberbliss

19. Websites and GitHub repos
My Spring REST repo containing examples: https://github.com/cyberbliss/springboot-rest-example
Swagger site: http://swagger.io/
Swagger spec: https://github.com/swagger-api/swagger-spec
Swagger Editor: https://github.com/swagger-api/swagger-editor
Online Swagger Editor: http://editor.swagger.io/
Swagger-Test: https://github.com/earldouglas/swagger-test
assertj-swagger: https://github.com/RobWin/assertj-swagger
Swagger2Markup: https://github.com/Swagger2Markup/swagger2markup-maven-plugin
RAML site: http://raml.org/
RAML spec: https://github.com/raml-org/raml-spec
RAML Editor: https://github.com/mulesoft/api-designer
abao tester: https://github.com/cybertk/abao/
RAML tester: https://github.com/nidi3/raml-tester
raml2html: https://github.com/kevinrenskers/raml2html
raml2Markdown: https://github.com/kevinrenskers/raml2md
API Blueprint site: https://apiblueprint.org/
API Blueprint spec: https://github.com/apiaryio/api-blueprint
API Blueprint tester: https://github.com/apiaryio/dredd
API Blueprint to HTML: https://github.com/danielgtaylor/aglio
Online Mock server generator: http://getsandbox.com
Code generation as a service: https://apimatic.io/