Vincenzo Chianese gave a presentation on bringing OpenAPI to DevOps. He discussed current usages of OpenAPI like documentation, code generation, and test automation. However, tooling has not fully caught up with the latest OpenAPI 3.0 specification. While some API gateways support OpenAPI, implementations can be difficult and OpenAPI's capabilities for describing runtime aspects of APIs are limited. Overall, better tooling and expanded OpenAPI specifications are still needed to fully bring OpenAPI to DevOps workflows and API management platforms.

1. Bringing OpenAPI to DevOps
Vincenzo Chianese — @d3dvincent

2. StoplightSaturday, May 25, 2019 @d3dvincent 2
Agenda
• Where are we at with OpenAPI
• Current usages and tools
• What’s up with OpenAPI at runtime
• Use cases
• API Gateway support
• What can we do better
• Live demo
• Takeaways and questions

3. StoplightSaturday, May 25, 2019 @d3dvincent 3
Vincenzo Chianese
• vincenzo@express-gateway.io
• vincenzo@stoplight.io
• https://vncz.js.org/
• https://twitter.com/D3DVincent
• https://github.com/XVincentX
Software Developer @ Stoplight
Maintainer @ Express Gateway
Auth0 Ambassador
Google Developer Expert

4. StoplightSaturday, May 25, 2019 @d3dvincent
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
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

5. StoplightSaturday, May 25, 2019 @d3dvincent
{
"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
Interactive documentation
ToC
Request/
Response
description
Online client
Linting
Search
Features
Client
generation
Content/
Type

6. StoplightSaturday, May 25, 2019 @d3dvincent 6
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"
}
},
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")
});
Base URL and
authentication
URL mapping
Parameters
mapping
Success and
error handlers

7. StoplightSaturday, May 25, 2019 @d3dvincent 7
Automation of test cases
Schema
validation
File
coverage

8. StoplightSaturday, May 25, 2019 @d3dvincent 8
Linting
Best
Practices
Business
rules
• Spectral
• Open Source Linting Engine
• Based on https://speccy.io
• https://github.com/stoplightio/spectral

9. StoplightSaturday, May 25, 2019 @d3dvincent 9
What about the runtime?
🤔

10. StoplightSaturday, May 25, 2019 @d3dvincent 10
OpenAPI in your runtime: today
• API Monitoring
• API Usage Statistics
• API Analysis and feedback collection

11. StoplightSaturday, May 25, 2019 @d3dvincent 11
OpenAPI as a source for verification
client.pets.list()
GET /api/pets
HOST: petstore.com
Accept: application/json
• Most used endpoints
• Most failing endpoints
• Most common scenarios

12. StoplightSaturday, May 25, 2019 @d3dvincent 12
…what about ops?
🤔
• Safely rollout a new API Section
• Set an API Section as deprecated
• Changes in security requirements
• Changes in validation rules
• Redirects
😫

13. StoplightSaturday, May 25, 2019 @d3dvincent 13
API Gateway
• Limited configuration surface
• Almost 1:1 match with OpenAPI description file
• (some) solutions can be declaratively configured

14. StoplightSaturday, May 25, 2019 @d3dvincent 14
AWS API Gateway
• OpenAPI 2 support
• OpenAPI 3 support (September 2018)
• Proprietary extensions
• Lack of an Document Upload API

15. StoplightSaturday, May 25, 2019 @d3dvincent 15
Axway API Gateway
• OpenAPI 2 support
• No custom extensions
• Public API for configuration
• Missing OpenAPI upload

16. StoplightSaturday, May 25, 2019 @d3dvincent 16
Apigee Edge
• Unclear OpenAPI supported version
• No documented extensions
• Project Upload API

17. StoplightSaturday, May 25, 2019 @d3dvincent 17
On premise/hybrid solutions
The situation does not seem to be that better
Express Gateway

18. StoplightSaturday, May 25, 2019 @d3dvincent 18
Express Gateway in a nutshell
Express GatewayTrusted by several companies

19. StoplightSaturday, May 25, 2019 @d3dvincent 19
Talk is cheap; show me the code

20. StoplightSaturday, May 25, 2019 @d3dvincent 20
Takeaways and open questions
• Tooling hasn’t caught up yet with OpenAPI 3.0
• Implementations difficulties
• OAS3 is not yet spread
• OAS2 is good enough
• OpenAPI aren’t a first class citizens for 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 specifications need to be expanded

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