Documenting APIs with Swagger

TC Camp
Peter Gruenbaum
 Introduction
} Covers
} What is an API Definition?
} YAML
} Open API Specification
} Writing Documentation
} Generating Documentation
} Alternatives to Swagger and the Open API Specification

} Presentation and workbook at sdkbridge.com/downloads

© 2018 SDK Bridge

 Peter Gruenbaum
} PhD in Applied Physics from Stanford
} Commercial Software Developer
} Boeing, Microsoft, start-ups
} C#, C++, Java, JavaScript, Objective-C
} API Writer
} Brought together writing and technology
} Since 2003
} President of SDK Bridge
} Teacher: Programming at middle, high school, and college
© 2018 SDK Bridge
 API Definition

} Swagger and the Open API Specification are ways to

define an API
} What is an API?
} What can you do with an API definition?

© 2018 SDK Bridge

 What are APIs?
} Application Programming Interface
} It defines how two pieces of software talk to each other
} For this seminar, we are talking about Web APIs

© 2018 SDK Bridge

 Web APIs

API request

API response
Creative Commons Attribution 3.0.
webdesignhot.com
Creative Commons Attribution 3.0.
Not a full web page ─ just the data! openclipart.org

The API definition describes:

• What requests are available
• What the response looks like for each request
© 2018 SDK Bridge
 REST
} Swagger and the Open API Specification are designed for
RESTful APIs
} REST is a type of web API

RE
REpresentational
S
State
T
Transfer
© 2018 SDK Bridge
 REST Requests and Responses
Please send
me the state
of my feed

API request

API response

I am transferring to you some

data that represents the state
of your feed

© 2018 SDK Bridge

 How many public APIs are there?

© 2018 SDK Bridge

 API Definition File
} File describes all the things you can do with an API
} Lists every request you can make
} Tells you how to make that request
} Tells you what the response will look like

© 2018 SDK Bridge

 Why Create an API Definition?
} Lets you design the API before implementing it
} Helps with automated testing
} Automatically create code in several languages
} Can be used to automatically generate documentation
} Documentation can be interactive

© 2018 SDK Bridge

 Swagger
} Historically, Swagger was a specification for how to create
an API definition file
} After a new version (Swagger 2.0), the specification
became the Open API Specification (OAS)
} Swagger is now a collection of tools that use the Open
API Specification
} Many people still refer to OAS as “Swagger”

© 2018 SDK Bridge

 Open API Initiative
} The Open API Initiative (OAI) is an organization created
by a consortium of industry experts
} Focused on creating, evolving, and promoting a vendor
neutral description format.
} It is in charge of the Open API Specification, but not in
charge of any tools that use it
} I will show you version 2.0, and talk about 3.0

© 2018 SDK Bridge

 Swagger Tools
Swagger provides several tools:
} Swagger Editor: Helps you write OAS files
} Swagger CodeGen: Generates code in popular languages
for using your API
} Swagger UI: Generates documentation from OAS files
} SwaggerHub: Hosted platform for designing and
documenting APIs

© 2018 SDK Bridge

 Documentation example placeholder
} http://petstore.swagger.io/

© 2018 SDK Bridge

YAML

Open API Specification Format

Documenting APIs with Swagger

 Open API Specification
} You can use one of two data formats for OAS:
} YAML
} JSON
} For this seminar, I’ll use YAML

© 2018 SDK Bridge

 YAML
} Stands for YAML Ain’t Markup Language
} It’s not a Markup Language like HTML
} Used for structured data instead of free-form content
} Compared to JSON and XML, it minimizes characters
} It's most often used for configuration files, rather than
files passed over the web, like JSON

© 2018 SDK Bridge

 Key/value pairs
} Key/value pairs are indicated by a colon followed by a
space

date: 2017-08-06
firstName: Peter

© 2018 SDK Bridge

 Levels
} Levels are indicated by white space indenting
} Cannot be a tab indent

<name>
<firstName>Peter</firstName>
XML <lastName>Gruenbaum</lastName>
</name>

name: { name:
JSON "firstName": "Peter"
"lastName": "Gruenbaum"
YAML firstName: Peter
lastName: Gruenbaum
}
© 2018 SDK Bridge
 Types
} Types are determined from context
} Example:
string
part_no: A4786
description: Photoresistor
price: 1.47 float
quantity: 4
integer

© 2018 SDK Bridge

 Quotes
} In general, you don’t need quotes around strings
} Exception: something that will be interpreted as a number
or boolean

float
price: 11.47
version: "11.47"
company: SDK Bridge string

} Quotes can be either single ' or double "

© 2018 SDK Bridge
 Lists
} Use a dash to indicate a cart:
list item - part_no: A4786
description: Photoresistor
} You don’t need to price: 1.47
declare the list quantity: 4

- part_no: B3443
description: LED
color: blue
price: 0.29
quantity: 12

© 2018 SDK Bridge

 Multi-line strings
} Because there are no quotation marks on strings, you need special
characters for multiline strings
} | means preserve lines and spaces
} > means fold lines
} There are variations: |-, |+, etc.
speech: | speech: >
Four score Four score
and seven years ago
and seven years ago
Four score
and seven years ago Four score and seven years ago
© 2018 SDK Bridge
 Comments
} Comments are denoted with the #
} Everything after # is ignored

# LED
part_no: B3443
description: LED
color: blue
price: 0.29 # US Dollars
quantity: 12

© 2018 SDK Bridge

 Schemas
} Although not officially part of YAML, OAS uses references
for schemas
} Used for request and response bodies
} Use $ref to indicate a reference
} Typically put the schema in a definitions section

© 2018 SDK Bridge

 Schema example
schema:
$ref: '#/definitions/user'
...
definitions:
user:
required:
- username
- id
properties:
username:
type: string
id:
type: integer
format: int64

© 2018 SDK Bridge

 Exercise 1: YAML
} Write some simple YAML
} Follow along in exercise book
} Electronic copy available at sdkbridge.com/downloads

© 2018 SDK Bridge

API Definition

What’s in an API Definition file?

Documenting APIs with Swagger
 What’s an API Definition File?
} A file that describes everything you can do with an API
} Note: “API” means a collection of related requests
} Server location
} How security is handled (i.e., authorization)
} All the available requests in that API
} All the different data you can send in a request
} What data is returned
} What HTTP status codes can be returned

© 2018 SDK Bridge

 The Anatomy of a Request
Method URL Query parameters

POST http://api.example.com/user?source=ios&device=ipad

Accept: application/json
Content-type: application/json Headers

{
"name": "Peter Gruenbaum",
"email": "peter@sdkbridge.com" Body
}

© 2018 SDK Bridge

 URL
} Example request URL: https://api.muzicplayz.com/v3/playlist
} Scheme
} https
} Host
} api.muzicplayz.com
} Base path
} /v3
} Path
} /playlist
© 2018 SDK Bridge
 Method
} The HTTP method describes what kind of action to take
} GET, POST, PUT, DELETE, etc.

© 2018 SDK Bridge

 Parameters
} Example:
} https://api.muzicplayz.com/v3/playlist/{playlist-id}?language=en
} Path Parameters
} {playlist-id}
} Query Parameters
} language

© 2018 SDK Bridge

 Request Body
} For some methods (POST, PUT, etc.) you can specify a
request body, often in JSON
} The body is treated as a parameter
} You specify a schema for the request body

© 2018 SDK Bridge

 Response Body
} In REST, the response body can be anything, but is most
often structured data, such as JSON
} The response object has a schema to describe the
structured data
} You can have a separate response object for each HTTP
status code returned

© 2018 SDK Bridge

 Security
} Security means authentication and authorization
} Can be:
} None
} Basic Auth
} API key
} OAuth

© 2018 SDK Bridge

 Documentation
} Human-readable descriptions of elements
} For generating documentation
} Add a “description” section for:
} The API
} Each operation (path and method)
} Each parameter
} Each response element
} Will go into detail in the next section
© 2018 SDK Bridge
 Getting the information to create an OAS file
} If you are asked to create an OAS file, how do you find
the information?
} Developers can provide rough documentation
} Developers can provide sample requests and responses
} Most common
} You can figure it out from the code
} Requires strong coding skills

© 2018 SDK Bridge

Open API Specification Basics

Defining Simple Requests

Documenting APIs with Swagger
 Open API Specification File
} Choose an example and build a file
} Company: example.com
} Service for uploading and sharing photos
} API base URL:
} https://api.example.com/photo

© 2018 SDK Bridge

 Example

© 2018 SDK Bridge

 Adding a Request
Let’s define requests for getting photo albums
Requests will have:
} URL endpoint
} HTTP Method
} Path parameters
} Query parameters
} Also (covered later):
} Request body
} Responses

© 2018 SDK Bridge

 Example with query parameters
GET https://api.example.com/photo/album?start=2017-09-01&end=2017-09-31

© 2018 SDK Bridge

 Example with path parameter
GET https://api.example.com/photo/album/123456

© 2018 SDK Bridge

 Data types
} The data type can have several values
} Includes:
} Boolean
} integer
} number
} string
} array

© 2018 SDK Bridge

 Custom headers
} Custom headers are treated as parameters
} Standard headers (authorization, content format) are
handled elsewhere

© 2018 SDK Bridge

 Documentation
} Documentation is added using the description key
} I will talk about this later in the workshop

© 2018 SDK Bridge

 Swagger Editor
} Swagger provides an editor for Open API Specification
files
} Go to http://editor2.swagger.io

© 2018 SDK Bridge

 Exercise 2: OAS Basics
} Create an OAS file for a music system
} The API manages playlists
} Describe overall API information, paths, methods, and
some parameters

© 2018 SDK Bridge

Schemas

Defining Request and Response Bodies

Learn Swagger and the Open API Specification

 Request and Response Bodies
} Certain kinds of requests have extra data
} POST, PUT, etc.
} Called the request body
} Typically data is formatted in JSON (or sometimes XML)
} Nearly all responses return a response body
} Also typically formatted in JSON

© 2018 SDK Bridge

 What is a schema?
} The schema indicates the structure of the data
} OAS schema object is based off the JSON Schema
Specification
} http://json-schema.org/
} What are the keys in key/value pairs?
} What type of data are the values?
} Can be many levels

© 2018 SDK Bridge

 $ref
} $ref is a special OAS key that indicates that the value is
a reference to a structure somewhere else in the YAML
file

© 2018 SDK Bridge

 Request Body
} Under parameters:
} name – just for reference (not shown in docs)
} in – set to body
} required – typically set to true
} schema –
} Add a level
} Key of $ref
} Value of the reference path, in quotes
© 2018 SDK Bridge
 Example Request Body

© 2018 SDK Bridge

 Schema section
} Create a key called definitions at the end of the file
} Add a level and give it the name from the $ref value
} Add a properties key
} For each top level element in the JSON, add a key of its
name.
} Add a type key that says what type of data it is
} Add other keys for other data (more later)

© 2018 SDK Bridge

 Example Schema

© 2018 SDK Bridge

 Schema objects
} You can add other objects as values
} Simply use a type of object
} Then add a new level with properties:
} And continue just like you did before

© 2018 SDK Bridge

 Schema objects with $ref
} As you can imagine, this can add a lot of indentation
} So you can use $ref from within your definition using
the additionalProperties key

© 2018 SDK Bridge

 Schema array
} You can also add arrays
} Simply use a type of array
} Then add a key of items
} And define the type and any other properties

© 2018 SDK Bridge

 Schema array with $ref
} For a more complex type, use $ref for the array items

© 2018 SDK Bridge

 Required
} In requests, you can specify that certain elements are
required or optional
} Use the required key for this
} Contains a list of all properties that are required

© 2018 SDK Bridge

 Response Body
} Under response:, under the response code
} schema:
} Add a level
} Key of $ref
} Value of the reference path, in quotes
} If the response is an array instead of an object, then add:
} type: array
} Note: you can have different schemas for different
response codes
© 2018 SDK Bridge
 Example Response

Note: The album schema is

identical to the newAlbum
schema except it has an id

© 2018 SDK Bridge

 allOf
} In the previous example, album and newAlbum had a lot
of duplication
} Can use the allOf key to combine several objects into
one

© 2018 SDK Bridge

 Headers and Examples
} Responses can also have custom headers
} You can include example bodies in OAS files
} Refer to the Open API Specification on how these work
} (Just search on “Open API Specification”)

© 2018 SDK Bridge

 Exercise 3: Schemas
} Add to your OAS file
} POST, PUT, and responses
} Describe overall API information, paths, methods, and
some parameters

© 2018 SDK Bridge

Open API Specification Continued

Security, errors, content types, and

operation IDs
Learn Swagger and the Open API Specification
 Security
} Security means what kind of authentication or
authorization is required
} Authentication: the user has correct username and
password
} Authorization: the user has access to this API and data

© 2018 SDK Bridge

 Security types
} None
} Used for getting publically available information
} API key
} Indicates that the app has permission to use the API
} Basic Authentication
} Username and password is included in a header
} OAuth
} Complex issuance of temporary token

© 2018 SDK Bridge

 How security is indicated
} Each operation has a security key
} Contains an array of security definition objects
} Often just one element in the array
} Security Definitions
} The file contains a securityDefinitions key
} Typically at the end
} Contains security objects
} Security object
} Contains information needed for that type of security

© 2018 SDK Bridge

 None
} When you do not have security…
} …you don’t need to do anything!

😀
© 2018 SDK Bridge
 API key
} Add security key to each operation
} Use dash to indicate an array
} Create name for definition and use empty bracket, since no
data is needed
} Add security definition
} Add definition for that name in securityDefinition section
} type: apiKey
} name: name of the header or query parameter to be used
} in: query or header
© 2018 SDK Bridge
 API key example
} Put a security key in the get section and
securityDefinitions at the end of the file

https://…?token=23a645ga2798

© 2018 SDK Bridge

 Basic authentication
} Add security key to an operation
} Use dash to indicate an array
} Create name for definition and use empty bracket, since no
data is needed
} Add security definition
} Add definition for that name in securityDefinition section
} type: basic

© 2018 SDK Bridge

 Basic auth example
} Put a security key in the get section and
securityDefinitions at the end of the file

© 2018 SDK Bridge

 OAuth
} OAuth is too complicated to explain here
} Add security key to request, like before
} However, now you add scopes in the array
} Add security definition
} Add definition for that name in securityDefinition section
} type: oauth2
} authorizationUrl: URL where credentials are entered
} tokenUrl: URL for the token
} flow: OAuth 2 flow (implicit, password, application or
accessCode.)
} scopes: list of scopes with descriptions

© 2018 SDK Bridge

 OAuth example
} Put a security key in the get section and
securityDefinitions at the end of the file

© 2018 SDK Bridge

 Errors
} Errors are simply different response codes
} Often APIs return a special structure with errors
} Example 401 (Unauthorized) code returned
{"errorCode": 13, "message": "Username not found"}
} Should include schema for every potential status code
} Refer to this in response

© 2018 SDK Bridge

 Error example

© 2018 SDK Bridge

 Content Types
} Content types indicate the format of the data in the
request and response bodies
} This is done through the Content-Type header
} You can specify this for:
} The whole API
} Individual operations
} Use the consumes and produces keys
} consumes for requests, produces for responses
} Use the Content-Type value (for example, application/json)
© 2018 SDK Bridge
 Example Content-Type

© 2018 SDK Bridge

 Operation ID
} Although it doesn’t show up in the documentation, you
can optionally add an operation ID to each request
} Some tools will use this

© 2018 SDK Bridge

 Exercise 4: OAS Continued
} Add to your OAS file:
} Security,
} Errors,
} Content type
} Operation IDs

© 2018 SDK Bridge

Documentation

Adding Descriptions
Document APIs Using Swagger
 Autogenerated Documentation
} Tools (including Swagger) take OAS files and generate
HTML documentation to put on the web
} If the OAS file is kept up to date, then the
documentation is likely to be more accurate than if you
wrote the docs manually
} Autogenerated documentation allows you to try out
requests from within the documentation

© 2018 SDK Bridge

 The Anatomy of a Request
Method URL Query parameters

POST http://api.example.com/user?source=ios&device=ipad

Accept: application/json
Content-type: application/json Headers

{
"name": "Peter Gruenbaum",
"email": "peter@sdkbridge.com" Body
}

© 2018 SDK Bridge

 description key
} Use the description key to add documentation
} Add description key to:
} API Info
} Operations (get, post, etc.)
} Parameters
} Responses
} Schema definitions

© 2018 SDK Bridge

 Swagger Editor Placeholder

} Bring up example on editor

© 2018 SDK Bridge

 Markdown
} In the description value, you can use Markdown
} Markdown is a simple Markup language
} Bold, italic, images, links, etc.

© 2018 SDK Bridge

 Markdown Placeholder

} Bring up example on editor

© 2018 SDK Bridge

 Exercise 5: Documentation
} Add documentation to your example
} See the effects on the right side of the page

© 2018 SDK Bridge

Swagger Tools

Editor, CodeGen, UI, and Core Tooling

Learn Swagger and the Open API Specification

 Swagger Tools Placeholder

} https://swagger.io/tools/

© 2018 SDK Bridge

 Swagger UI
} Autogenerated documentation
} For example, pet store documentation
} There are other ways to create autogenerated
documentation
} https://swagger.io/swagger-ui/

© 2018 SDK Bridge

 SwaggerHub
} Provides all of the tools on a hosted platform
} As of this video:
} Free for one user
} $75/month for team of 5
} Advantages:
} Don’t have to install and host
} Designed for collaboration

© 2018 SDK Bridge

 Exercise 6: SwaggerHub
} Try out SwaggerHub for free
} Import your OAS file

© 2018 SDK Bridge

OAS 3.0

The Next Generation

Document APIs with Swagger
 Several changes from 2.0
} Improved overall structure
} Support for callbacks
} Links to express relationships between operations
} The JSON schema includes support for: oneOf, anyOf and not
} Improved parameter descriptions
} Better support for multipart document handling
} Cookie parameters
} Body parameters have their own entity
} Better support for content-type negotiation
} The security definitions have been simplified and enhanced
© 2018 SDK Bridge
JSON

Alternative to YAML
Learn Swagger and the Open API Specification
 Why JSON?
} Older format
} Some people may be more familiar with it than YAML
} Some tools only read JSON

© 2018 SDK Bridge

 YAML vs JSON
} In JSON, strings have quotes around them
} YAML indents are like JSON curly brackets { }
} YAML lists are like JSON arrays [ ]

© 2018 SDK Bridge

 Comparison
YAML JSON
{
info: "info":
version: "0.1.0" {
title: Meme Meister "version": "0.1.0"
description: Meme API "title": "Meme Meister"
"description": "Meme API"
}
}
© 2018 SDK Bridge
 Arrays
YAML JSON
{
consumes: "consumes":
- image/jpeg [
- image/gif "image/jpeg",
- image/png "image/gif",
"image/png",
]
}
© 2018 SDK Bridge
 Advantages of YAML
} Fewer characters
} Easier to read
} Swagger uses YAML as the default
} However, you can use the Swagger Editor with JSON just like
you use it with YAML

© 2018 SDK Bridge

Alternatives to Swagger

Other autogenerated doc tools

Document APIs with Swagger
 Alternatives to Swagger
} Swagger is great, but…
} Some people think it could be better
} In particular, the autogenerated documentation
} Not “responsive”, not that pretty, etc.
} In theory, you can take OAS files and do whatever you
want with them
} There are several alternatives to Swagger
} Disclaimer: I am not an expert in any of these
© 2018 SDK Bridge
 DapperDox

} http://dapperdox.io

© 2018 SDK Bridge

 Swagger UI Variants

} https://github.com/jensoleg/swagger-ui

© 2018 SDK Bridge

 ReadMe.io

} http://readme.io

© 2018 SDK Bridge

 StopLight.io

} http://stoplight.io

© 2018 SDK Bridge

 Alternatives to OAS
} OAS is just one way to define an API
} There are other specifications that have been created
} RAML
} API Blueprint
} Not as popular as OAS

© 2018 SDK Bridge

 Resources

} I’d Rather Be Writing - Tom Johnson

} Sarah Maddox
} SDK Bridge Online courses
} Last page of workbook has links with discounts

© 2018 SDK Bridge

 Exercise 7: Final Project
} Create an OAS file for a Meme API from scratch
} Not an easy assignment
} In the electronic version of the workbook only

© 2018 SDK Bridge

 Questions?

© 2018 SDK Bridge