This session will show you how you can easily document your REST API's using Spring & Swagger. It will show you how to use the Swagger-Spring integration in a Spring Boot application: Setup a basic REST API using Spring-Boot together with Swagger-Springfox Access and test the REST-API using the Swagger-UI client Generate client code stubs for your language (e.g. Java, PHP, Python, ...) using Swagger-Codegen Graphically display your REST-API using the Chrome plugin Swagger.ed Devoxx Belgium Nov. 2015

1. @johannes_fiala#Devoxx #Swagger
Document your REST-API and
generate client-code
using Swagger and Spring
Johannes Fiala
FWD

2. @johannes_fiala#Devoxx #Swagger
In the next few minutes you‘ll learn
how to…
• provide documentation for your REST-API
• access your API with a browser using Swagger UI
• generate client code for accessing your API
• get a nice picture of your API services & models

3. @johannes_fiala#Devoxx #Swagger
Swagger
• A language-agnostic interface to REST APIs
• allows to discover and understand the capabilities of a service
• Swagger removes the guesswork in calling the service
• Swagger renders the API docs in JSON syntax
“A standardized way to describe an API in JSON syntax”
Source: https://github.com/swagger-api/swagger-spec

4. @johannes_fiala#Devoxx #Swagger
Technology stack
• Spring
• Spring Boot for fast start
• Also possible for Spring REST applications
• Springfox
• For providing the dynamic api-docs
• Swagger UI
• For accessing the api using a browser
• Swagger Codegen
• For generating client code stubs

5. @johannes_fiala#Devoxx #Swagger
Big Picture
Your REST-API
Springfox
/v2/api-docs/
Swagger-UI
/swagger/index.html
Swagger-
Codegen
Client-Code
Java, PHP, C#, Ruby, nodejs,
Objective-C, …

6. @johannes_fiala#Devoxx #Swagger
Springfox
• Provide complete api-docs for every @RESTController
• Services
• Supported Verbs (GET/POST/…)
• Request parameters/body
• Response codes + body
• Many customization options (hide attributes, custom data
types, …)

7. @johannes_fiala#Devoxx #Swagger
Swagger UI
• Javascript application for accessing your complete REST
API using a browser
• Lists all services directly from the (dynamic) api-docs
• Always consistent with your API!

8. @johannes_fiala#Devoxx #Swagger
Swagger Codegen
• Client code stub generator (commandline)
• Generates client stubs (customizable!)
• Supported languages:
• Java, C#, Dart, Flash, Groovy, JaxRS, NodeJS,
Objective-C, Perl, PHP, Python, Ruby, Scala, ….

9. @johannes_fiala#Devoxx #Swagger
Why generate client code?
• Ensure consistency of your client code with the API!
• Makes code completion possible!
• For service methods & model classes
• Allows developers to read description for your operations
and models in the IDE
• You get compilation errors if the API breaks with newer
versions!

10. Demo
@YourTwitterHandle#Devoxx #Swagger

11. @johannes_fiala#Devoxx #Swagger
Swagger Codegenerator
• Code generation templates:
• DefaultCodegenerator.generate():
• Scans Model Properties first
• Then compliles the Mustache templates
• Language specifics:
• io.swagger.codegen.languages.*
• Mustache files

12. @johannes_fiala#Devoxx #Swagger
Wrapup
• Springfox: provide api-docs
• Completely dynamic & Always consistent
• Swagger-UI: access api-docs using browser
• make your api-docs easily acessible for testers/developers/…
• Swagger-Codegen: generate client stubs
• Get code completion
• Keep your clients in sync
• Swagger.Ed: display your API graphically

13. @johannes_fiala#Devoxx #Swagger
Enable Swagger/Springfox
• Add dependencies
• Add @EnableSwagger2 to Application
• Run your spring application

14. @johannes_fiala#Devoxx #Swagger
Springfox annotations
• Controller:
• @Api
• Operations:
• @ApiOperation – describe your service
• @ApiResponse – Define error codes
• Model:
• @ApiModel(„description“)
• @ApiModelProperty: description + required-flag
• @JsonIgnore

15. @johannes_fiala#Devoxx #Swagger
Swagger-UI
• Ship together with your REST-service
• Makes accessing your services easy
• Protect the Swagger-UI if applicable

16. @johannes_fiala#Devoxx #Swagger
Use Swagger Codegen
• Call using the commandline
• Integrate with your build environment (e.g. using Ant)

17. @johannes_fiala#Devoxx #Swagger
Swagger.Ed
• Chrome Plugin for visually displaying you API
• Allows users to graphically explore through your services
& models
• Nice for „Big picture“ of your API

18. @johannes_fiala#Devoxx #Swagger
Who is using Swagger?
• Paypal
• Microsoft
• Amazon AWS API gateway:
• http://swagger.io/getting-started-with-the-amazon-swagger-
importer/
• You can import Swagger definitions here
• You can manage your services using Amazon AWS then

19. @johannes_fiala#Devoxx #Swagger
More sessions about Swagger
• Thursday BOF 21:00-22:00:
How to get code completion for existing REST APIs
using Swagger (e.g. Facebook Graph API)
• Come if you like to see how this can be done!
• Demo with Facebook Graph API

20. @johannes_fiala#Devoxx #Swagger
Links & Resources
• Swagger.io
http://swagger.io
• Swagger.io integrations
http://swagger.io/open-source-integrations/
• Springfox
http://springfox.github.io/springfox/

21. @johannes_fiala#Devoxx #Swagger
Links & Resources
• Swagger UI
https://github.com/swagger-api/swagger-ui
• Swagger Codegen
https://github.com/swagger-api/swagger-codegen
• Chrome Plugin Swagger.ed
https://github.com/chefArchitect/apispots-browser-
swaggered

22. @johannes_fiala#Devoxx #Swagger
Questions ???

23. @johannes_fiala#Devoxx #Swagger
Thank you for your attention!
• Contact:
• johannes.fiala@fwd.at