Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition...

transcript

STC Webinar

Peter Gruenbaum

Documenting APIs with Swagger

Introduction

Covers

What is an API Definition?

Open API Specification

Writing Documentation

Generating Documentation

Alternatives to Swagger and the Open API Specification

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

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?

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

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!

Swagger and the Open API Specification are designed for

RESTful APIs

REST is a type of web API

REpresentational

Transfer

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

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

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

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”

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

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

Documentation example placeholder

http://petstore.swagger.io/

Open API Specification Format

Open API Specification

You can use one of two data formats for OAS:

For this seminar, I’ll use 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

Key/value pairs

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

date: 2017-08-06

firstName: Peter

Levels

Levels are indicated by white space indenting

Cannot be a tab indent

YAMLname: {

"firstName": "Peter"

"lastName": "Gruenbaum"

<name>

<firstName>Peter</firstName>

<lastName>Gruenbaum</lastName>

</name>

firstName: Peter

lastName: Gruenbaum

Types are determined from context

Example:

part_no: A4786

description: Photoresistor

price: 1.47

quantity: 4

string

integer

Use a dash to indicate a

list item

You don’t need to

declare the list

- part_no: A4786

description: Photoresistor

price: 1.47

quantity: 4

- part_no: B3443

description: LED

color: blue

price: 0.29

quantity: 12

Comments Comments are denoted with the #

Everything after # is ignored

part_no: B3443

description: LED

color: blue

price: 0.29 # US Dollars

quantity: 12

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

Schema exampleschema:

$ref: '#/definitions/user'

definitions:

required:

- username

properties:

username:

type: string

type: integer

format: int64

What’s in an API Definition file?

API Definition

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

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": "peter@sdkbridge.com"

Method URL Query parameters

Headers

Example request URL: https://api.muzicplayz.com/v3/playlist

Scheme

api.muzicplayz.com

Base path

/playlist

Method

The HTTP method describes what kind of action to take

GET, POST, PUT, DELETE, etc.

Parameters

Example:

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

Path Parameters

{playlist-id}

Query Parameters

language

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

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

Security

Security means authentication and authorization

Can be:

Basic Auth

API key

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

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

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

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": "peter@sdkbridge.com"

Method URL Query parameters

Headers

description key

Use the description key to add documentation

Add description key to:

API Info

Operations (get, post, etc.)

Parameters

Responses

Schema definitions

Swagger Editor Placeholder

Bring up example on editor

Markdown

In the description value, you can use Markdown

Markdown is a simple Markup language

Bold, italic, images, links, etc.

Markdown Placeholder

Bring up example on editor

The Next Generation

Document APIs with Swagger

OAS 3.0

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

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

DapperDox

http://dapperdox.io

Swagger UI Variants

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

ReadMe.io

http://readme.io

StopLight.io

http://stoplight.io

Alternatives to OAS

OAS is just one way to define an API

There are other specifications that have been created

API Blueprint

Not as popular as OAS

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

Questions?

Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition...

Documents