Introduction to Open

API Specification
 
Lorna Mitchell, Nexmo
Describing APIs
• Describe RESTful HTTP APIs in a machine-readable way
• API description is independent of outputs such as
documentation
• Enable things that are not "just" documentation

@lornajane
Spec-First API Design

@lornajane
About OpenAPI Spec
API description language formerly known as "Swagger".
 
Became "OpenAPI Spec" -> v3 released
 
(some tools are still catching up on v3)

@lornajane
New APIs or Existing Ones?

@lornajane
 New APIs or Existing Ones?
 
Yes!

@lornajane
Who Writes OpenAPI Specs?

@lornajane
Anatomy of OpenAPI Spec

@lornajane
Anatomy of OpenAPI Spec
Top-level elements:
• openapi
• info
• servers
• paths
• components
• security
• tags

@lornajane
OpenAPI Spec Examples
A JSON or YAML file holds the description (this is YAML)
openapi: 3.0.0
servers:
- url: 'https://api.nexmo.com'
info:
version: 1.0.0
title: Secret Management API

... a few hundred more lines here

@lornajane
Documenting an Endpoint
paths:
/accounts/{account_id}/secrets:
get:
summary: Retrieve API Secrets
operationId: retrieveSecrets
parameters:
- $ref: '#/components/parameters/accountId'
responses:
'200': ...
'401':
$ref: '#/components/responses/BadCredentialsError'
'404':
$ref: '#/components/responses/NotFoundError'

@lornajane
Example 200 Response
description: API secret response
content:
application/json:
schema:
properties:
secrets:
type: object
description: A list of secrets under the "secrets" key.
properties:
secrets:
type: array
items:
$ref: '#/components/schemas/SecretInfo'

@lornajane
SecretInfo Reference
schemas:
SecretInfo:
type: object
properties:
id:
type: string
description: Secret ID
example: ad6dc56f-07b5-46e1-a527-85530e625800
created_at:
type: string
description: The date/time the secret was created
example: '2017-03-02T16:34:49Z'

@lornajane
 That looks complicated!
 

@lornajane
Rendered Example: ReDoc

@lornajane
Rendered Example: Nexmo

@lornajane
Tools To Get Things Done

@lornajane
Please use Source Control

See also: https://gitworkbook.com

@lornajane
Editing Tools
There are editors with helpful tools
• I like Atom with linter-swagger https://atom.io
• Try SwaggerUI, SwaggerHub, etc https://swagger.io/tools/
• APICurio Studio gets good reviews https://www.apicur.io/
• Stoplight looks interesting https://stoplight.io
 
(feel free to tweet your best tools at me, I'll share them all later)

@lornajane
OAS in Atom

@lornajane
Validation Tools
Tools that check or "lint" your file.
• Speccy is a CLI tool with configurable rules http://speccy.io/
• Open API Spec Validator
https://github.com/p1c2u/openapi-spec-validator
 
Set up in your editor or use a watch command, e.g.:
watch -n 1 speccy lint myspec.yml

@lornajane
Preview Tools
OAS is a standard! So any preview should do:
• ReDoc is great https://github.com/Rebilly/ReDoc
• Speccy also wraps ReDoc for its serve command
• You can run OpenApi-GUI locally
https://github.com/mermade/openapi-gui

@lornajane
Creating OpenAPI Specs is like
eating an elephant

@lornajane
Uses for OpenAPI Spec

@lornajane
Resources
• https://www.openapis.org
• https://apievangelist.com
• https://speccy.io
• https://github.com/Rebilly/ReDoc
• https://openapi.tools

@lornajane