Documenting APIs 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 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. 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 <name> <firstName>Peter</firstName> XML <lastName>Gruenbaum</lastName> </name> 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