Upload
jworks-powered-by-ordina
View
416
Download
3
Embed Size (px)
Citation preview
Ordina JOIN 2014
Ken Coenen@CoenenKen
Senior Java DeveloperArchitecture & Best Practices Competence Lead at Ordina
Documenting your REST API with SWAGGER
Swagger?
“Swagger is a specification and complete framework implementation for describing, producing, consuming, and
visualizing RESTful web services.”
Describing
Swagger specification
▪ JSON description of your REST API▪ APIs▪ Methods▪ Models
▪ Conversion from YAML to Swagger available▪ No need to write this yourself
JSON description of your API
JSON description of a method
JSON description of a model
Producing and consuming
SDK generators
{ Swagger API spec }
Client code Server code
Framework integration
Documentation generation with Jersey
1. Include Maven dependency (watch out for exclusions!)
Needed for annotation classes
Documentation generation with Jersey (2)
2. Replace regular Jersey servlet with Swagger version
Documentation generation with Jersey (3)
4. API description available on /api/api-docs
3. Annotate your REST services with Swagger annotations
Client codegen
1. Written in Scala2. {{ mustache }} templates 3. Maven goal4. Generate eg. Java code into a separate Maven module5. Add Maven dependency to consuming modules
Client codegen pros and 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
Visualizing
Swagger UI API
Swagger UI method
Links
▪ Starting point is 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
Conclusion
Swagger conclusions
▪ Documentation close to server code▪ SwaggerUI is major advantage▪ Don’t expect client codegen to work out-of-the-box
Q&A