A Tour of Swagger for APIs

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


Swagger is a specification…

…for describing a REST API


And Swagger is a…

…set of core tools© 2015 International Business Machines Corporation 5

And more tools…



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…


• A framework that helps to produce and consume APIs and helps visualize.

• A specification that helps describe and document them.


A technology and a methodology

How do you start?



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


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


Write Swagger-compliant JSON


Manually create with Swagger Editor


Generate from annotations


Add Swagger to an existing API

Find out what Swagger gives you for free: Annotate only your methods:

@Api() and @ApiOperation annotations:


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


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


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


• JSON object• Can use YAML to

construct it

• Version 2 is current• Swagger UI is backward

compatible with v1.2


Swagger-compliant file


Swagger UI

Can run locally and display hosted APIs


Swagger Editor

Can view a swagger file without the Swagger UI


Swagger-core annotations

Output is swagger-compliant


Swagger-tools

Showing validation from the CLI


Swagger.ed

A visualization tool


Swagger-ed

Is Swagger for you?


• 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


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


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


A Tour of Swagger for APIs

Technology

Transcript of A Tour of Swagger for APIs