Documenting 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 Developer } Boeing, Microsoft, start-ups } #, 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 REpresentational State 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 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-06 firstName: Peter

© 2018 SDK Bridge Levels

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

Peter XML Gruenbaum

name: { name: JSON "firstName": "Peter" YAML firstName: Peter "lastName": "Gruenbaum" 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 Headers Content-type: application/json

{ "name": "Peter Gruenbaum", "email": "[email protected]" 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-Ty p e 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-Ty p e 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 Headers Content-type: application/json

{ "name": "Peter Gruenbaum", "email": "[email protected]" 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