Documenting APIs with Swagger. TC Camp. Peter Gruenbaum

Transcription

1 Documenting APIs with Swagger TC Camp Peter Gruenbaum

2 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

3 Peter Gruenbaum } } PhD in Applied Physics from Stanford Commercial Software Developer } } } API Writer } } } } Boeing, Microsoft, start-ups C#, C++, Java, JavaScript, Objective-C Brought together writing and technology Since 2003 President of SDK Bridge Teacher: Programming at middle, high school, and college

4 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?

5 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

6 Web APIs API request Creative Commons Attribution 3.0. webdesignhot.com Not a full web page just the data! API response Creative Commons Attribution 3.0. openclipart.org The API definition describes: What requests are available What the response looks like for each request

7 REST } Swagger and the Open API Specification are designed for RESTful APIs } REST is a type of web API REpresentational State Transfer

8 REST Requests and Responses API request Please send me the state of my feed API response I am transferring to you some data that represents the state of your feed

9 How many public APIs are there?

10 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

11 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

12 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

13 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

14 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

15 Documentation example placeholder }

16 YAML Open API Specification Format Documenting APIs with Swagger

17 Open API Specification } You can use one of two data formats for OAS: } YAML } JSON } For this seminar, I ll use YAML

18 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

19 Key/value pairs } Key/value pairs are indicated by a colon followed by a space date: firstname: Peter

20 Levels } Levels are indicated by white space indenting } Cannot be a tab indent XML <name> <firstname>peter</firstname> <lastname>gruenbaum</lastname> </name> JSON name: { "firstname": "Peter" "lastname": "Gruenbaum" } YAML name: firstname: Peter lastname: Gruenbaum

21 Types } Types are determined from context } Example: string part_no: A4786 description: Photoresistor price: 1.47 float quantity: 4 integer

22 Quotes } In general, you don t need quotes around strings } Exception: something that will be interpreted as a number or boolean price: version: "11.47" company: SDK Bridge float string } Quotes can be either single ' or double "

23 Lists } Use a dash to indicate a list item } You don t need to declare the list cart: - part_no: A4786 description: Photoresistor price: 1.47 quantity: 4 - part_no: B3443 description: LED color: blue price: 0.29 quantity: 12

24 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 score and seven years ago speech: > Four score and seven years ago Four score and seven years ago Four score and seven years ago

25 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

26 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

27 Schema example schema: $ref: '#/definitions/user'... definitions: user: required: - username - id properties: username: type: string id: type: integer format: int64

28 Exercise 1: YAML } Write some simple YAML } Follow along in exercise book } Electronic copy available at sdkbridge.com/downloads

29 API Definition What s in an API Definition file? Documenting APIs with Swagger

30 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

31 The Anatomy of a Request Method URL Query parameters POST Accept: application/json Content-type: application/json Headers { } "name": "Peter Gruenbaum", " ": "peter@sdkbridge.com" Body

32 URL } Example request URL: } Scheme } https } Host } api.muzicplayz.com } Base path } /v3 } Path } /playlist

33 Method } The HTTP method describes what kind of action to take } GET, POST, PUT, DELETE, etc.

34 Parameters } Example: } } Path Parameters } {playlist-id} } Query Parameters } language

35 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

36 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

37 Security } Security means authentication and authorization } Can be: } None } Basic Auth } API key } OAuth

38 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

39 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

40 Open API Specification Basics Defining Simple Requests Documenting APIs with Swagger

41 Open API Specification File } Choose an example and build a file } Company: example.com } Service for uploading and sharing photos } API base URL: }

42 Example

43 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

44 Example with query parameters GET

45 Example with path parameter GET

46 Data types } The data type can have several values } Includes: } Boolean } integer } number } string } array

47 Custom headers } Custom headers are treated as parameters } Standard headers (authorization, content format) are handled elsewhere

48 Documentation } Documentation is added using the description key } I will talk about this later in the workshop

49 Swagger Editor } Swagger provides an editor for Open API Specification files } Go to

50 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

51 Schemas Defining Request and Response Bodies Learn Swagger and the Open API Specification

52 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

53 What is a schema? } The schema indicates the structure of the data } OAS schema object is based off the JSON Schema Specification } } What are the keys in key/value pairs? } What type of data are the values? } Can be many levels

54 $ref } $ref is a special OAS key that indicates that the value is a reference to a structure somewhere else in the YAML file

55 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

56 Example Request Body

57 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)

58 Example Schema

59 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

60 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

61 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

62 Schema array with $ref } For a more complex type, use $ref for the array items

63 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

64 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

65 Example Response Note: The album schema is identical to the newalbum schema except it has an id

66 allof } In the previous example, album and newalbum had a lot of duplication } Can use the allof key to combine several objects into one

67 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 )

68 Exercise 3: Schemas } Add to your OAS file } POST, PUT, and responses } Describe overall API information, paths, methods, and some parameters

69 Open API Specification Continued Security, errors, content types, and operation IDs Learn Swagger and the Open API Specification

70 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

71 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

72 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

73 None } When you do not have security } you don t need to do anything!

74 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

75 API key example } Put a security key in the get section and securitydefinitions at the end of the file

76 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

77 Basic auth example } Put a security key in the get section and securitydefinitions at the end of the file

78 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

79 OAuth example } Put a security key in the get section and securitydefinitions at the end of the file

80 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

81 Error example

82 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)

83 Example Content-Type

84 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

85 Exercise 4: OAS Continued } Add to your OAS file: } Security, } Errors, } Content type } Operation IDs

86 Documentation Adding Descriptions Document APIs Using Swagger

87 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

88 The Anatomy of a Request Method URL Query parameters POST Accept: application/json Content-type: application/json Headers { } "name": "Peter Gruenbaum", " ": "peter@sdkbridge.com" Body

89 description key } Use the description key to add documentation } Add description key to: } API Info } Operations (get, post, etc.) } Parameters } Responses } Schema definitions

90 Swagger Editor Placeholder } Bring up example on editor

91 Markdown } In the description value, you can use Markdown } Markdown is a simple Markup language } Bold, italic, images, links, etc.

92 Markdown Placeholder } Bring up example on editor

93 Exercise 5: Documentation } Add documentation to your example } See the effects on the right side of the page

94 Swagger Tools Editor, CodeGen, UI, and Core Tooling Learn Swagger and the Open API Specification

95 Swagger Tools Placeholder }

96 Swagger UI } Autogenerated documentation } For example, pet store documentation } There are other ways to create autogenerated documentation }

97 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

98 Exercise 6: SwaggerHub } Try out SwaggerHub for free } Import your OAS file

99 OAS 3.0 The Next Generation Document APIs with Swagger

100 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

101 JSON Alternative to YAML Learn Swagger and the Open API Specification

102 Why JSON? } Older format } Some people may be more familiar with it than YAML } Some tools only read JSON

103 YAML vs JSON } In JSON, strings have quotes around them } YAML indents are like JSON curly brackets { } } YAML lists are like JSON arrays [ ]

104 Comparison YAML info: version: "0.1.0" title: Meme Meister description: Meme API { } JSON "info": { "version": "0.1.0" "title": "Meme Meister" "description": "Meme API" }

105 Arrays YAML consumes: - image/jpeg - image/gif - image/png { } JSON "consumes": [ "image/jpeg", "image/gif", "image/png", ]

106 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

107 Alternatives to Swagger Other autogenerated doc tools Document APIs with Swagger

108 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

109 DapperDox }

110 Swagger UI Variants }

111 ReadMe.io }

112 StopLight.io }

113 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

114 Resources } I d Rather Be Writing - Tom Johnson } Sarah Maddox } SDK Bridge Online courses } Last page of workbook has links with discounts

115 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

116 Questions?