documenting your rest api with swagger - join 2014

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