Bringing OpenAPI to DevOps: How OpenAPI Specification Enables Interactive Documentation, Code Generation, Automated Testing and More

Bringing OpenAPI to DevOps
Vincenzo Chianese — @d3dvincent

StoplightMonday, May 20, 2019 @d3dvincent 2
Agenda

Agenda
• Where are we at with OpenAPI

Agenda
• Current usages and tools

Agenda
• What’s up with OpenAPI at runtime

Agenda
• Use cases

Agenda
• Use cases
• API Gateway support

Agenda
• Use cases
• What can we do better

Agenda
• Use cases
• Live demo

Agenda
• Use cases
• Live demo
• Takeaways and questions

Vincenzo Chianese

Vincenzo Chianese
Software Developer @ Stoplight

Vincenzo Chianese
Maintainer @ Express Gateway

Vincenzo Chianese
Auth0 Ambassador

Vincenzo Chianese
Auth0 Ambassador
Google Developer Expert

Vincenzo Chianese
• vincenzo@express-gateway.io

• vincenzo@stoplight.io

• https://vncz.js.org/

• https://twitter.com/D3DVincent

• https://github.com/XVincentX
Auth0 Ambassador
Google Developer Expert

StoplightMonday, May 20, 2019 @d3dvincent
OpenAPI
4

OpenAPI
4
The OpenAPI Specification (OAS) defines a standard,
programming language-agnostic interface description
for REST APIs, which allows both humans and
computers to discover and understand the capabilities
of a service

OpenAPI
4
of a service
Use cases for machine-readable API definition
documents include, but are not limited to: interactive
documentation; code generation for documentation,
clients, and servers; and automation of test cases.

OpenAPI
4
of a service
Use cases for machine-readable API definition
documents include, but are not limited to: interactive
documentation; code generation for documentation,
clients, and servers; and automation of test cases.
— OpenAPI Official Repository

Interactive documentation

{
"swagger": "2.0",
"info": {
"description": "This is a sample server Petstore server.",
"version": "1.0.0",
"title": "Swagger Petstore",
"termsOfService": "http://swagger.io/terms/",
"contact": {
"email": "apiteam@swagger.io"
},
"license": {
"name": "Apache 2.0",
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
}
},
5

ToC

ToC
Request/
Response
description

ToC
Request/
Response
description
Online client

ToC
Request/
Response
description
Online client
Linting

ToC
Request/
Response
description
Online client
Linting
Search
Features

ToC
Request/
Response
description
Online client
Linting
Search
Features
Client
generation

ToC
Request/
Response
description
Online client
Linting
Search
Features
Client
generation
Content/
Type

Code generation
{
"swagger": "2.0",
"info": {
"description": "This is a sample server Petstore server.",
"version": "1.0.0",
"title": "Swagger Petstore",
"termsOfService": "http://swagger.io/terms/",
"contact": {
"email": "apiteam@swagger.io"
},
"license": {
"name": "Apache 2.0",
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
}
},

Code generation
const client = require(‘petstore-client')
(process.env.PETSTORE_API_KEY);
client.pets.create({
name: 'Doogy',
age: 2
}).then(() => {
console.log("Pet created correctly!");
}).catch(() => {
console.error("Something went wrong")
});

Code generation
name: 'Doogy',
age: 2
}).then(() => {
}).catch(() => {
});
Base URL and
authentication

Code generation
name: 'Doogy',
age: 2
}).then(() => {
}).catch(() => {
});
Base URL and
authentication
URL mapping

Code generation
name: 'Doogy',
age: 2
}).then(() => {
}).catch(() => {
});
Base URL and
authentication
URL mapping
Parameters
mapping

Code generation
name: 'Doogy',
age: 2
}).then(() => {
}).catch(() => {
});
Base URL and
authentication
URL mapping
Parameters
mapping
Success and
error handlers

Automation of test cases

Schema
validation

Schema
validation
File
coverage

Linting

Linting
Best
Practices

Linting
Best
Practices
Business
rules

Linting
• Open Source Linting Engine

Linting
• Based on https://speccy.io

Linting
• Based on https://speccy.io
• https://github.com/stoplightio/spectral

Mocking

Mocking
Try the API

Mocking
Try the API
Stub the
responses

Mocking
• Prism 3

Mocking
• Prism 3
• Open Source Mock Server

Mocking
• Prism 3
• Complete rewrite in TypeScript

Mocking
• Prism 3
• Complete rewrite in TypeScript
• https://github.com/stoplightio/prism

What about the runtime?
🤔

OpenAPI in your runtime: today

• API Monitoring

• API Monitoring
• API Usage Statistics

• API Monitoring
• API Usage Statistics
• API Analysis and feedback collection

OpenAPI as a source for verification

client.pets.list()

client.pets.list()
GET /api/pets 
HOST: petstore.com
Accept: application/json

client.pets.list()
GET /api/pets 
HOST: petstore.com
• Most used endpoints

client.pets.list()
GET /api/pets 
HOST: petstore.com
• Most failing endpoints

client.pets.list()
GET /api/pets 
HOST: petstore.com
• Most failing endpoints
• Most common scenarios

…what about ops?
🤔

…what about ops?
🤔
• Safely rollout a new API Section

…what about ops?
🤔
• Set an API Section as deprecated

…what about ops?
🤔
• Changes in security requirements

…what about ops?
🤔
• Changes in validation rules

…what about ops?
🤔
• Redirects

…what about ops?
• Redirects
😫

API Gateway

API Gateway
• Limited conﬁguration surface

API Gateway
• Almost 1:1 match with OpenAPI description ﬁle

API Gateway
• Almost 1:1 match with OpenAPI description ﬁle
• (some) solutions can be declaratively conﬁgured

AWS API Gateway

AWS API Gateway
• OpenAPI 2 support

AWS API Gateway

AWS API Gateway
• Proprietary extensions

AWS API Gateway
• Document Upload API

AWS API Gateway
• Document Upload API
• Merge feature

Apigee Edge

Apigee Edge
• OpenAPI 2.0 support

Apigee Edge

Apigee Edge
• No documented extensions

Apigee Edge
• No documented extensions
• Project Upload API

Microsoft API Management

• Few, not super important, extensions

• Few, not super important, extensions
• Project Upload API

Open Source Solutions

The situation is not that cool

The situation is not that cool
Express Gateway

Express Gateway in a nutshell

Express Gateway

Express Gateway Trusted by several companies

Talk is cheap; show me the code

Takeaways and open questions

• OpenAPI aren’t a ﬁrst class citizens for Open Source API Gateways

• They just do not care of its support

• Not the right tool for the job

• OpenAPI documents alone aren’t enough to describe all the aspects of an API

• OpenAPI documents alone aren’t enough to describe all the aspects of an API
• OpenAPI speciﬁcations need to be expanded

The rules (to make it happen)

• Use an API Gateway

• Put as much as you can on it (security, rate limiting, payload validation)

• You do not need micro services to use an API Gateway

• Make sure what exposes matches what’s declared in the OpenAPI spec ﬁle

• Prefer a solution that is declarative

• It’s going to be easier to write automation scripts

• Refrain from using custom extension

• Refrain from using custom extension
• It will complicate the things the day these automations will be the standard for all the
solutions

Thank you!
• vincenzo@express-gateway.io
• vincenzo@stoplight.io
• https://vncz.js.org/
• https://twitter.com/D3DVincent
• https://github.com/XVincentX

Bringing OpenAPI to DevOps: How OpenAPI Specification Enables Interactive Documentation, Code Generation, Automated Testing and More

Recommended

Recommended

More Related Content

Similar to Bringing OpenAPI to DevOps: How OpenAPI Specification Enables Interactive Documentation, Code Generation, Automated Testing and More

Similar to Bringing OpenAPI to DevOps: How OpenAPI Specification Enables Interactive Documentation, Code Generation, Automated Testing and More (20)

More from Nordic APIs

More from Nordic APIs (20)

Recently uploaded

Recently uploaded (20)

Bringing OpenAPI to DevOps: How OpenAPI Specification Enables Interactive Documentation, Code Generation, Automated Testing and More