Zen and the Art of REST API documentation - MuCon London 2015
- 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
- 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 ✔✔✔ ✔ ✔
- 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/