Date post: | 09-Aug-2015 |
Category: |
Technology |
Upload: | allen-dean |
View: | 270 times |
Download: | 4 times |
A tour of Swagger for (REST) APIs
Allen DeanInformation Development, IBM Watson™
#stc15
Swagger is API documentation
Right?
© 2015 International Business Machines Corporation 2
Well yes. But, just one of the tools…
…called Swagger UI
© 2015 International Business Machines Corporation 3
Swagger is a specification…
…for describing a REST API
© 2015 International Business Machines Corporation 4
And Swagger is a…
…set of core tools© 2015 International Business Machines Corporation 5
And more tools…
© 2015 International Business Machines Corporation 6
© 2015 International Business Machines Corporation 7
A robust community
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
• 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
How do you start?
© 2015 International Business Machines Corporation 10
© 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
© 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
© 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
© 2015 International Business Machines Corporation 14
Write Swagger-compliant JSON
© 2015 International Business Machines Corporation 15
Manually create with Swagger Editor
© 2015 International Business Machines Corporation 16
Generate from annotations
© 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:
© 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
© 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
© 2015 International Business Machines Corporation 20
Regularly built JSONFor 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
© 2015 International Business Machines Corporation 21
JSON at run timeDocumentation 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
Survey of tools and components
© 2015 International Business Machines Corporation 22
• 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
© 2015 International Business Machines Corporation 24
Swagger UI
Can run locally and display hosted APIs
© 2015 International Business Machines Corporation 25
Swagger Editor
Can view a swagger file without the Swagger UI
© 2015 International Business Machines Corporation 26
Swagger-core annotations
Output is swagger-compliant
© 2015 International Business Machines Corporation 27
Swagger-tools
Showing validation from the CLI
© 2015 International Business Machines Corporation 28
Swagger.ed
A visualization tool
© 2015 International Business Machines Corporation 29
Swagger-ed
Is Swagger for you?
© 2015 International Business Machines Corporation 30
• 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…
• 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…
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/apispots/swaggered/
• API Description Languages: Which is the Right One for Me? http://www.slideshare.net/SOA_Software/api-description-languages-which-is-the-right-one-for-me
© 2015 International Business Machines Corporation #stc15 33
Questions
© 2015 International Business Machines Corporation 34