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.
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/