Going to Infinity and Beyond Documentation with OpenAPI Specification

Person dreaming of self documenting APIs

Single Source of Truth

So you've built an API...

What is the OpenAPI Specification? (formerly known as Swagger)

Standard, structured approach for describing REST APIs that is both human and machine readable

Overview of the section of an OpenAPI document

An OpenAPI document looks like:

openapi: 3.0.0 info: version: 1.0.0 title: “Corgi API” (and it goes on…)

components: schemas: Corgi: required: (and it goes on…)

Lead Community Engineer at Stoplight

email -> taylor@stoplight.io twitter -> taylor_atx

Bridge with HTTP on it

Bridge with HTTP on it and humans written below

Hidden OpenAPI Benefits

It is NOT just for API References

  • Development contract
  • Prototype and mocking
  • Client libraries and SDKs
  • Testing
  • Server stubs

More than a technical representation

Tool for Collaboration

Simplifies Standardizes