Download as PDF, PPTX
Uploaded byJWORKS powered by Ordina
Documenting your REST API with Swagger - JOIN 2014
The document discusses the use of Swagger for documenting REST APIs, emphasizing its specifications and framework for producing, consuming, and visualizing web services. It covers various aspects such as JSON descriptions, documentation generation with Jersey, and client code generation, highlighting the pros and cons of client code generation. The conclusion stresses the advantages of having documentation close to server code and the benefits of using Swagger UI.
More Related Content
Similar to Documenting your REST API with Swagger - JOIN 2014
Documenting your REST API with Swagger - JOIN 2014
- 1. Ordina JOIN 2014 KenCoenen @CoenenKen Senior Java Developer Architecture & Best Practices Competence Lead at Ordina Documenting your REST API with SWAGGER
- 2. Swagger? “Swagger is aspecification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services.”
- 3.
- 4. Swagger specification ▪ JSONdescription of your REST API ▪ APIs ▪ Methods ▪ Models ▪ Conversion from YAML to Swagger available ▪ No need to write this yourself
- 5. JSON description ofyour API
- 6. JSON description ofa method
- 7. JSON description ofa model
- 8.
- 9. SDK generators { SwaggerAPI spec } Client code Server code
- 10.
- 11. Documentation generation withJersey 1. Include Maven dependency (watch out for exclusions!) Needed for annotation classes
- 12. Documentation generation withJersey (2) 2. Replace regular Jersey servlet with Swagger version
- 13. Documentation generation withJersey (3) 4. API description available on /api/api-docs 3. Annotate your REST services with Swagger annotations
- 14. Client codegen 1. Writtenin Scala 2. {{ mustache }} templates 3. Maven goal 4. Generate eg. Java code into a separate Maven module 5. Add Maven dependency to consuming modules
- 15. Client codegen prosand cons ▪ All clients have latest code by executing Codegen ▪ Make sure client code serializes/deserializes objects the same as your backend ▪ Session management ▪ Multithreading ▪ Maven integration is hard
- 16.
- 17.
- 18.
- 19. Links ▪ Starting pointis http://swagger.io/ ▪ GitHub https://github.com/wordnik/swagger-spec ▪ Codegen project https://github.com/wordnik/swagger-codegen ▪ YAML to Swagger https://github.com/wordnik/swagger- codegen/blob/master/bin/yml2swagger.js
- 20.
- 21. Swagger conclusions ▪ Documentationclose to server code ▪ SwaggerUI is major advantage ▪ Don’t expect client codegen to work out-of-the-box
- 22.