Documenting APIs with Swagger - SDK Bridgesdkbridge.com/tc/tcpresentation.pdfSwagger}Historically,...
Transcript of Documenting APIs with Swagger - SDK Bridgesdkbridge.com/tc/tcpresentation.pdfSwagger}Historically,...
TC Camp
Peter Gruenbaum
Documenting APIs with Swagger
© 2018 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
} 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.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!
© 2018 SDK Bridge
REST} Swagger and the Open API Specification are designed for
RESTful APIs} REST is a type of web API
REpresentationalState Transfer
REST
© 2018 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 stateof 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 ToolsSwagger 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/
Open API Specification Format
Documenting APIs with Swagger
YAML
© 2018 SDK Bridge
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 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
© 2018 SDK Bridge
Key/value pairs} Key/value pairs are indicated by a colon followed by a
space
date: 2017-08-06firstName: Peter
© 2018 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: PeterlastName: Gruenbaum
© 2018 SDK Bridge
Types} Types are determined from context} Example:
part_no: A4786 description: Photoresistorprice: 1.47 quantity: 4
string
float
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
} Quotes can be either single ' or double "
price: 11.47 version: "11.47"company: SDK Bridge string
float
© 2018 SDK Bridge
Lists} Use a dash to indicate a
list item} You don’t need to
declare the list
cart:- part_no: A4786 description: Photoresistorprice: 1.47 quantity: 4
- part_no: B3443description: LEDcolor: blueprice: 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: |
Four scoreand seven years ago
Four scoreand seven years ago
speech: >
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
# LEDpart_no: B3443description: LEDcolor: blue price: 0.29 # US Dollarsquantity: 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 exampleschema:$ref: '#/definitions/user'
...definitions:user:required:- username- id
properties:username:type: string
id:type: integerformat: int64
© 2018 SDK Bridge
Exercise 1: YAML} Write some simple YAML} Follow along in exercise book} Electronic copy available at sdkbridge.com/downloads
What’s in an API Definition file?
Documenting APIs with Swagger
API Definition
© 2018 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
© 2018 SDK Bridge
The Anatomy of a Request
POST http://api.example.com/user?source=ios&device=ipad
Accept: application/jsonContent-type: application/json
{ "name": "Peter Gruenbaum","email": "[email protected]"
}
Method URL Query parameters
Headers
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
Defining Simple Requests
Documenting APIs with Swagger
Open API Specification Basics
© 2018 SDK Bridge
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 RequestLet’s define requests for getting photo albumsRequests will have:} URL endpoint} HTTP Method} Path parameters} Query parameters} Also (covered later):
} Request body} Responses
© 2018 SDK Bridge
Example with query parametersGET https://api.example.com/photo/album?start=2017-09-01&end=2017-09-31
© 2018 SDK Bridge
Example with path parameterGET 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
Defining Request and Response Bodies
Learn Swagger and the Open API Specification
Schemas
© 2018 SDK Bridge
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 newAlbumschema 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
Security, errors, content types, and operation IDs
Learn Swagger and the Open API Specification
Open API Specification Continued
© 2018 SDK Bridge
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
Adding Descriptions
Document APIs Using Swagger
Documentation
© 2018 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
© 2018 SDK Bridge
The Anatomy of a Request
POST http://api.example.com/user?source=ios&device=ipad
Accept: application/jsonContent-type: application/json
{ "name": "Peter Gruenbaum","email": "[email protected]"
}
Method URL Query parameters
Headers
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
Editor, CodeGen, UI, and Core Tooling
Learn Swagger and the Open API Specification
Swagger Tools
© 2018 SDK Bridge
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
The Next Generation
Document APIs with Swagger
OAS 3.0
© 2018 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
Alternative to YAML
Learn Swagger and the Open API Specification
JSON
© 2018 SDK Bridge
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
info:
version: "0.1.0"
title: Meme Meister
description: Meme API
{
"info":
{
"version": "0.1.0"
"title": "Meme Meister"
"description": "Meme API"
}
}
YAML JSON
© 2018 SDK Bridge
Arrays
consumes:
- image/jpeg
- image/gif
- image/png
{
"consumes":
[
"image/jpeg",
"image/gif",
"image/png",
]
}
YAML JSON
© 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
Other autogenerated doc tools
Document APIs with Swagger
Alternatives to Swagger
© 2018 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
© 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?