53
STC Webinar Peter Gruenbaum Documenting APIs with Swagger
STC Webinar
Peter Gruenbaum
Documenting APIs with Swagger
© 2017 SDK Bridge
Introduction
Covers
What is an API Definition?
YAML
Open API Specification
Writing Documentation
Generating Documentation
Alternatives to Swagger and the Open API Specification
© 2017 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
© 2017 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?
© 2017 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
© 2017 SDK Bridge
Web APIs
API request
API response
Creative Commons Attribution 3.0.
openclipart.org
Creative Commons Attribution 3.0.
webdesignhot.com
The API definition describes:
• What requests are available
• What the response looks like for each request
Not a full web page ─ just the data!
© 2017 SDK Bridge
REST
Swagger and the Open API Specification are designed for
RESTful APIs
REST is a type of web API
REpresentational
State
Transfer
RE
S
T
© 2017 SDK Bridge
REST Requests and Responses
API request
API response
Please send
me the state
of my feed
I am transferring to you some
data that represents the state
of your feed
© 2017 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
© 2017 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
© 2017 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”
© 2017 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
© 2017 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
© 2017 SDK Bridge
Documentation example placeholder
http://petstore.swagger.io/
Open API Specification Format
Documenting APIs with Swagger
YAML
© 2017 SDK Bridge
Open API Specification
You can use one of two data formats for OAS:
YAML
JSON
For this seminar, I’ll use YAML
© 2017 SDK Bridge
YAML
Stands forYAML 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
© 2017 SDK Bridge
Key/value pairs
Key/value pairs are indicated by a colon followed by a
space
date: 2017-08-06
firstName: Peter
© 2017 SDK Bridge
Levels
Levels are indicated by white space indenting
Cannot be a tab indent
JSON
XML
YAMLname: {
"firstName": "Peter"
"lastName": "Gruenbaum"
}
<name>
<firstName>Peter</firstName>
<lastName>Gruenbaum</lastName>
</name>
name:
firstName: Peter
lastName: Gruenbaum
© 2017 SDK Bridge
Types
Types are determined from context
Example:
part_no: A4786
description: Photoresistor
price: 1.47
quantity: 4
string
float
integer
© 2017 SDK Bridge
Lists
Use a dash to indicate a
list item
You don’t need to
declare the list
cart:
- part_no: A4786
description: Photoresistor
price: 1.47
quantity: 4
- part_no: B3443
description: LED
color: blue
price: 0.29
quantity: 12
© 2017 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
© 2017 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
© 2017 SDK Bridge
Schema exampleschema:
$ref: '#/definitions/user'
...
definitions:
user:
required:
- username
- id
properties:
username:
type: string
id:
type: integer
format: int64
What’s in an API Definition file?
Documenting APIs with Swagger
API Definition
© 2017 SDK Bridge
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
© 2017 SDK Bridge
The Anatomy of a Request
POST http://api.example.com/user?source=ios&device=ipad
Accept: application/json
Content-type: application/json
{
"name": "Peter Gruenbaum",
"email": "[email protected]"
}
Method URL Query parameters
Headers
Body
© 2017 SDK Bridge
URL
Example request URL: https://api.muzicplayz.com/v3/playlist
Scheme
https
Host
api.muzicplayz.com
Base path
/v3
Path
/playlist
© 2017 SDK Bridge
Method
The HTTP method describes what kind of action to take
GET, POST, PUT, DELETE, etc.
© 2017 SDK Bridge
Parameters
Example:
https://api.muzicplayz.com/v3/playlist/{playlist-id}?language=en
Path Parameters
{playlist-id}
Query Parameters
language
© 2017 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
© 2017 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
© 2017 SDK Bridge
Security
Security means authentication and authorization
Can be:
None
Basic Auth
API key
OAuth
© 2017 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
© 2017 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
Adding Descriptions
Document APIs Using Swagger
Documentation
© 2017 SDK Bridge
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
© 2017 SDK Bridge
The Anatomy of a Request
POST http://api.example.com/user?source=ios&device=ipad
Accept: application/json
Content-type: application/json
{
"name": "Peter Gruenbaum",
"email": "[email protected]"
}
Method URL Query parameters
Headers
Body
© 2017 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
© 2017 SDK Bridge
Swagger Editor Placeholder
Bring up example on editor
© 2017 SDK Bridge
Markdown
In the description value, you can use Markdown
Markdown is a simple Markup language
Bold, italic, images, links, etc.
© 2017 SDK Bridge
Markdown Placeholder
Bring up example on editor
The Next Generation
Document APIs with Swagger
OAS 3.0
© 2017 SDK Bridge
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
Other autogenerated doc tools
Document APIs with Swagger
Alternatives to Swagger
© 2017 SDK Bridge
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
© 2017 SDK Bridge
Swagger UI Variants
https://github.com/jensoleg/swagger-ui
© 2017 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
© 2017 SDK Bridge
Resources
I’d Rather Be Writing - Tom Johnson
Sarah Maddox
SDK Bridge Online courses
sdkbridge.com/online-courses
Use code STC to get discount
SDK Bridge is available for writing and consulting
© 2017 SDK Bridge
Questions?
