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

© 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