Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Document your rest api using swagger - Devoxx 2015

1,584 views

Published on

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

Published in: Technology
  • Be the first to comment

Document your rest api using swagger - Devoxx 2015

  1. 1. @johannes_fiala#Devoxx #Swagger Document your REST-API and generate client-code using Swagger and Spring Johannes Fiala FWD
  2. 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. 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. 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. 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. 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. 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. 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. 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. 10. Demo @YourTwitterHandle#Devoxx #Swagger
  11. 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. 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. 13. @johannes_fiala#Devoxx #Swagger Enable Swagger/Springfox • Add dependencies • Add @EnableSwagger2 to Application • Run your spring application
  14. 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. 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. 16. @johannes_fiala#Devoxx #Swagger Use Swagger Codegen • Call using the commandline • Integrate with your build environment (e.g. using Ant)
  17. 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. 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. 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. 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. 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. 22. @johannes_fiala#Devoxx #Swagger Questions ???
  23. 23. @johannes_fiala#Devoxx #Swagger Thank you for your attention! • Contact: • johannes.fiala@fwd.at

×