[go: up one dir, main page]
Scribd
Upload
460 views31 pages

Intro To Oas

The document introduces OpenAPI specification for describing RESTful APIs. It discusses that OpenAPI specification describes APIs in a machine-readable way and enables capabilities beyond documentation. It also outlines the anatomy of an OpenAPI specification including top-level elements like info, servers, paths, components, etc. The document provides examples of documenting an endpoint and parameters in an OpenAPI specification.

Uploaded by

Rog Don
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
460 views31 pages

Intro To Oas

The document introduces OpenAPI specification for describing RESTful APIs. It discusses that OpenAPI specification describes APIs in a machine-readable way and enables capabilities beyond documentation. It also outlines the anatomy of an OpenAPI specification including top-level elements like info, servers, paths, components, etc. The document provides examples of documenting an endpoint and parameters in an OpenAPI specification.

Uploaded by

Rog Don
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 31

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/ni'
info:
title: Number Insight API
version: 1.1.0
description: >-
Nexmo's Number Insight API delivers real-time intelligence about the vali

... a few hundred more lines here

@lornajane
Documenting an Endpoint
paths:
'/basic/{format}':
parameters:
- $ref: '#/components/parameters/format'
get:
operationId: getNumberInsightBasic
parameters:
- $ref: '#/components/parameters/number'
- $ref: '#/components/parameters/country'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/niResponseJsonBasic'

@lornajane
Example Parameter
number:
name: number
in: query
description: 'A single phone number that you need insight about in national or
example: '447700900000'
required: true
schema:
type: string
pattern: '^[0-9-+\(\)\s]*$'

@lornajane
Example Response
niResponseJsonBasic:
type: object
properties:
status:
$ref: '#/components/schemas/niBasicStatus'
status_message:
type: string
description: 'The status description of your request.'
example: 'Success'
request_id:
type: string
description: 'The unique identifier for your request. This is a alphanumeri
example: 'aaaaaaaa-bbbb-cccc-dddd-0123456789ab'
maxLength: 40

...

@lornajane
That looks complicated!
 

@lornajane
Rendered Example: ReDoc

@lornajane
Rendered Example: Nexmo

@lornajane
Imported into Postman

@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
• https://github.com/openapitools/openapi-generator

@lornajane
 

@lornajane
Bonus Extra Slides

@lornajane
Code Generators
Libraries can be generated as easily as docs.
 
For PHP (and so many other languages) try
https://github.com/openapitools/openapi-generator
 
Pull docker image, generate PHP code from your OpenAPI Spec

@lornajane
Code Generator Example
1 $config->setUsername(NEXMO_API_KEY);
2 $config->setPassword(NEXMO_API_SECRET);
3
4 $client = new OpenAPI\Client\Api\DefaultApi(
5 new GuzzleHttp\Client(), $config);
6 $obj = new \OpenAPI\Client\Model\InlineObject();
7
8 try {
9 $result = $client->retrieveSecrets(NEXMO_API_KEY, $obj);
10 print_r($result);
11 } catch (Exception $e) {
12 echo 'Exception when calling DefaultApi->retrieveSecrets: ', $e->getMessag
13 }

@lornajane
Code Generator Example
1 $config->setUsername(NEXMO_API_KEY);
2 $config->setPassword(NEXMO_API_SECRET);
3
4 $client = new OpenAPI\Client\Api\DefaultApi(
5 new GuzzleHttp\Client(), $config);
6 $obj = new \OpenAPI\Client\Model\InlineObject();
7
8 try {
9 $result = $client->retrieveSecrets(NEXMO_API_KEY, $obj);
10 print_r($result);
11 } catch (Exception $e) {
12 echo 'Exception when calling DefaultApi->retrieveSecrets: ', $e->getMessag
13 }

@lornajane

You might also like