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.

A Tour of Swagger for APIs

2,071 views

Published on

Helps you to understand Swagger and its practical uses for representing REST APIs. You’ll learn some ways to get started. We’ll survey some of the tools and resources for describing REST APIs with Swagger. We’ll talk about what Swagger is (a specification and framework) — and isn’t (merely another doc tool). We’ll talk about the pros and cons of the Swagger-UI. And we’ll look at how Swagger helps people to learn about and explore an API.

Published in: Technology
  • Be the first to comment

A Tour of Swagger for APIs

  1. 1. A tour of Swagger for (REST) APIs Allen Dean Information Development, IBM Watson™ #stc15
  2. 2. Swagger is API documentation Right? © 2015 International Business Machines Corporation 2
  3. 3. Well yes. But, just one of the tools… …called Swagger UI © 2015 International Business Machines Corporation 3
  4. 4. Swagger is a specification… …for describing a REST API © 2015 International Business Machines Corporation 4
  5. 5. And Swagger is a… …set of core tools © 2015 International Business Machines Corporation 5
  6. 6. And more tools… © 2015 International Business Machines Corporation 6
  7. 7. © 2015 International Business Machines Corporation 7 A robust community
  8. 8. Lots of support… …through community tools • Projects by languages: • Clojure, Go, Java, JavaScript, .Net, Node.js, PERL, PHP, Python, Ruby.. • Projects by frameworks or platforms: • Angular.js, Apache (Ant, Maven, Wink), Django, Express, Flask, Gradle, Grunt, MongoDB, Spring… • Projects by types • Servers, clients, converters, generators, parsers, validators… © 2015 International Business Machines Corporation 8
  9. 9. • A framework that helps to produce and consume APIs and helps visualize. • A specification that helps describe and document them. © 2015 International Business Machines Corporation 9 A technology and a methodology
  10. 10. How do you start? © 2015 International Business Machines Corporation 10
  11. 11. © 2015 International Business Machines Corporation 11 Decide how to create and deliver • Type of output • Online and hosted: Swagger UI (a JSON object) • File-based or offline: (HTML, markdown, etc.) • Method to create Swagger JSON • Generate from code (annotations) • Manually: write JSON by hand • Design and build: Swagger Node • When to generate from code • Build regularly • Create at run time
  12. 12. © 2015 International Business Machines Corporation 12 Type of output • Online: • Swagger UI runs in a web browser. • Not set up for printing or viewing offline • Static: HTML and other static outputs: • Swagger codegen • Generate the Swagger JSON and a simple HTML file • bootprint-swagger project • Swagger to HTML • Swagger2Markup project • Designed to integrate Swagger generated output with other API documentation
  13. 13. © 2015 International Business Machines Corporation 13 Decide how to create and deliver • Type of output • Online and hosted: Swagger UI (a JSON object) • File-based or offline: (HTML, markdown, etc.) • Method to create Swagger JSON • Generate from code (annotations) • Manually: write JSON by hand • Design and build: Swagger Node • When to generate from code • Build regularly • Create at run time
  14. 14. © 2015 International Business Machines Corporation 14 Write Swagger-compliant JSON
  15. 15. © 2015 International Business Machines Corporation 15 Manually create with Swagger Editor
  16. 16. © 2015 International Business Machines Corporation 16 Generate from annotations
  17. 17. © 2015 International Business Machines Corporation 17 Add Swagger to an existing API Find out what Swagger gives you for free: Annotate only your methods: @Api() and @ApiOperation annotations:
  18. 18. © 2015 International Business Machines Corporation 18 Hand-crafted JSON vs. annotations • Hand-craft: For when you don’t have access to the code • Annotations: Easier to maintain. More in sync. Developers can own or share • Characteristics: • Delivered online through the Swagger UI or converted to static • Generated from annotations or lovingly hand-crafted • Potential issues with hand crafting • "Oh the pain" of writing JSON • Docs in sync only as of last writing
  19. 19. © 2015 International Business Machines Corporation 19 Decide how to create and deliver • Type of output • Online and hosted: Swagger UI (a JSON object) • File-based or offline: (HTML, markdown, etc.) • Method to create Swagger JSON • Generate from code (annotations) • Manually: write JSON by hand • Design and build: Swagger Node • When to generate from code • Build regularly • Create at run time
  20. 20. © 2015 International Business Machines Corporation 20 Regularly built JSON For when you are not ready to generate at run time. •Characteristics: • Delivered online through the Swagger UI or converted to static • Generated from annotations •Potential issues • Docs in sync only as of last writing
  21. 21. © 2015 International Business Machines Corporation 21 JSON at run time Documentation is always in sync with the code •Characteristics: • Delivered online through the Swagger UI • Created from annotations • Generated at run time •Potential issues • Can be technically challenging
  22. 22. Survey of tools and components © 2015 International Business Machines Corporation 22
  23. 23. • JSON object • Can use YAML to construct it • Version 2 is current • Swagger UI is backward compatible with v1.2 © 2015 International Business Machines Corporation 23 Swagger-compliant file
  24. 24. © 2015 International Business Machines Corporation 24 Swagger UI Can run locally and display hosted APIs
  25. 25. © 2015 International Business Machines Corporation 25 Swagger Editor Can view a swagger file without the Swagger UI
  26. 26. © 2015 International Business Machines Corporation 26 Swagger-core annotations Output is swagger-compliant
  27. 27. © 2015 International Business Machines Corporation 27 Swagger-tools Showing validation from the CLI
  28. 28. © 2015 International Business Machines Corporation 28 Swagger.ed A visualization tool
  29. 29. © 2015 International Business Machines Corporation 29 Swagger-ed
  30. 30. Is Swagger for you? © 2015 International Business Machines Corporation 30
  31. 31. • Can generate reference docs from existing APIs • Useful in visualizing and testing your API • Easy to share • An active community (questions get answered, bugs get addressed, and features get added) • Works with a lot of languages, platforms, frameworks • Open source. Licensed under Apache • It has an API explorer © 2015 International Business Machines Corporation 31 Swagger is a good choice because…
  32. 32. • Your APIs are not good RESTful citizens • Swagger works best with REST • Your APIs are complex and Swagger might not be "expressive" enough • You don't like the look of the Swagger UI • Difficult to customize • It has an API explorer © 2015 International Business Machines Corporation 32 Swagger is not for you because…
  33. 33. Where to find out more Delivered by Swagger • Swagger website: http://swagger.io/ • Swagger demo: http://petstore.swagger.io/ • Swagger Editor: http://editor.swagger.io/ • Swagger Google Group: https://groups.google.com/forum/#! forum/swagger-swaggersocket • GitHub: https://github.com/swagger-api From others • Api Evangelist: Swagger: http://swagger.apievangelist.com/ • Swagger.ed: http://chefarchitect.github.io/apispo ts/swaggered/ • API Description Languages: Which is the Right One for Me? http://www.slideshare.net/SOA_Soft ware/api-description-languages- which-is-the-right-one-for-me © 2015 International Business Machines Corporation #stc15 33
  34. 34. Questions © 2015 International Business Machines Corporation 34

×