Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition...
Transcript of Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition...
![Page 1: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/1.jpg)
STC Webinar
Peter Gruenbaum
Documenting APIs with Swagger
![Page 2: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/2.jpg)
© 2017 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
![Page 3: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/3.jpg)
© 2017 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
![Page 4: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/4.jpg)
© 2017 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?
![Page 5: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/5.jpg)
© 2017 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
![Page 6: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/6.jpg)
© 2017 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!
![Page 7: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/7.jpg)
© 2017 SDK Bridge
REST
Swagger and the Open API Specification are designed for
RESTful APIs
REST is a type of web API
REpresentational
State
Transfer
RE
S
T
![Page 8: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/8.jpg)
© 2017 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 state
of your feed
![Page 9: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/9.jpg)
© 2017 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
![Page 10: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/10.jpg)
© 2017 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
![Page 11: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/11.jpg)
© 2017 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”
![Page 12: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/12.jpg)
© 2017 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
![Page 13: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/13.jpg)
© 2017 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
![Page 14: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/14.jpg)
© 2017 SDK Bridge
Documentation example placeholder
http://petstore.swagger.io/
![Page 15: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/15.jpg)
Open API Specification Format
Documenting APIs with Swagger
YAML
![Page 16: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/16.jpg)
© 2017 SDK Bridge
Open API Specification
You can use one of two data formats for OAS:
YAML
JSON
For this seminar, I’ll use YAML
![Page 17: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/17.jpg)
© 2017 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
![Page 18: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/18.jpg)
© 2017 SDK Bridge
Key/value pairs
Key/value pairs are indicated by a colon followed by a
space
date: 2017-08-06
firstName: Peter
![Page 19: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/19.jpg)
© 2017 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: Peter
lastName: Gruenbaum
![Page 20: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/20.jpg)
© 2017 SDK Bridge
Types
Types are determined from context
Example:
part_no: A4786
description: Photoresistor
price: 1.47
quantity: 4
string
float
integer
![Page 21: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/21.jpg)
© 2017 SDK Bridge
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
![Page 22: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/22.jpg)
© 2017 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
![Page 23: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/23.jpg)
© 2017 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
![Page 24: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/24.jpg)
© 2017 SDK Bridge
Schema exampleschema:
$ref: '#/definitions/user'
...
definitions:
user:
required:
- username
- id
properties:
username:
type: string
id:
type: integer
format: int64
![Page 25: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/25.jpg)
What’s in an API Definition file?
Documenting APIs with Swagger
API Definition
![Page 26: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/26.jpg)
© 2017 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
![Page 27: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/27.jpg)
© 2017 SDK Bridge
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": "[email protected]"
}
Method URL Query parameters
Headers
Body
![Page 28: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/28.jpg)
© 2017 SDK Bridge
URL
Example request URL: https://api.muzicplayz.com/v3/playlist
Scheme
https
Host
api.muzicplayz.com
Base path
/v3
Path
/playlist
![Page 29: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/29.jpg)
© 2017 SDK Bridge
Method
The HTTP method describes what kind of action to take
GET, POST, PUT, DELETE, etc.
![Page 30: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/30.jpg)
© 2017 SDK Bridge
Parameters
Example:
https://api.muzicplayz.com/v3/playlist/{playlist-id}?language=en
Path Parameters
{playlist-id}
Query Parameters
language
![Page 31: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/31.jpg)
© 2017 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
![Page 32: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/32.jpg)
© 2017 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
![Page 33: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/33.jpg)
© 2017 SDK Bridge
Security
Security means authentication and authorization
Can be:
None
Basic Auth
API key
OAuth
![Page 34: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/34.jpg)
© 2017 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
![Page 35: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/35.jpg)
© 2017 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
![Page 36: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/36.jpg)
Adding Descriptions
Document APIs Using Swagger
Documentation
![Page 37: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/37.jpg)
© 2017 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
![Page 38: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/38.jpg)
© 2017 SDK Bridge
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": "[email protected]"
}
Method URL Query parameters
Headers
Body
![Page 39: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/39.jpg)
© 2017 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
![Page 40: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/40.jpg)
© 2017 SDK Bridge
Swagger Editor Placeholder
Bring up example on editor
![Page 41: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/41.jpg)
© 2017 SDK Bridge
Markdown
In the description value, you can use Markdown
Markdown is a simple Markup language
Bold, italic, images, links, etc.
![Page 42: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/42.jpg)
© 2017 SDK Bridge
Markdown Placeholder
Bring up example on editor
![Page 43: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/43.jpg)
The Next Generation
Document APIs with Swagger
OAS 3.0
![Page 44: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/44.jpg)
© 2017 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
![Page 45: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/45.jpg)
Other autogenerated doc tools
Document APIs with Swagger
Alternatives to Swagger
![Page 46: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/46.jpg)
© 2017 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
![Page 48: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/48.jpg)
© 2017 SDK Bridge
Swagger UI Variants
https://github.com/jensoleg/swagger-ui
![Page 51: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/51.jpg)
© 2017 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
![Page 52: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/52.jpg)
© 2017 SDK Bridge
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
![Page 53: Documenting APIs with Swagger - STC – PSC Swagger.pdf · © 2017 SDK Bridge API Definition Swagger and the Open API Specification are ways to define an API What is an API? What](https://reader036.fdocuments.net/reader036/viewer/2022062916/5ec579a26f458307fe416c6a/html5/thumbnails/53.jpg)
© 2017 SDK Bridge
Questions?