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


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?


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


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


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


© 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


© 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

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

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

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

Markdown} In the description value, you can use Markdown

} Markdown is a simple Markup language

} Bold, italic, images, links, etc.

© 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


Swagger 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

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


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

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

Documenting APIs with Swagger - SDK Bridgesdkbridge.com/tc/tcpresentation.pdfSwagger}Historically,...

Documents

Transcript of Documenting APIs with Swagger - SDK Bridgesdkbridge.com/tc/tcpresentation.pdfSwagger}Historically,...