Swagger is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services. The overarching goal of Swagger is to enable client and documentation systems to update at the same pace as the server. The documentation of methods, parameters, and models are tightly integrated into the server code, allowing APIs to always stay in sync. With Swagger, deploying managing, and using powerful APIs has never been easier.

1. Ordina JOIN 2014
Ken Coenen
@CoenenKen
Senior Java Developer
Architecture & Best Practices Competence Lead at Ordina
Documenting your REST API with
SWAGGER

2. Swagger?
“Swagger is a specification and complete framework
implementation for describing, producing, consuming, and
visualizing RESTful web services.”

3. Describing

4. Swagger specification
▪ JSON description of your REST API
▪ APIs
▪ Methods
▪ Models
▪ Conversion from YAML to Swagger available
▪ No need to write this yourself

5. JSON description of your API

6. JSON description of a method

7. JSON description of a model

8. Producing and consuming

9. SDK generators
{ Swagger API spec }
Client code Server code

10. Framework integration

11. Documentation generation with Jersey
1. Include Maven dependency
(watch out for exclusions!)
Needed for annotation classes

12. Documentation generation with Jersey (2)
2. Replace regular Jersey servlet with Swagger version

13. Documentation generation with Jersey (3)
4. API description available on
/api/api-docs
3. Annotate your REST services with
Swagger annotations

14. Client codegen
1. Written in 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 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

16. Visualizing

17. Swagger UI API

18. Swagger UI method

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

20. Conclusion

21. Swagger conclusions
▪ Documentation close to server code
▪ SwaggerUI is major advantage
▪ Don’t expect client codegen to work out-of-the-box

22. Q&A