OpenAPI and Swagger

By Tom Johnson / @tomjohnson

Slides available at

Video recording

The following is a video recording of this presentation.

What I'll talk about

  • Concepts more than technical details
  • The kind of documentation engineers want
  • Swagger UI and how to use it
  • OpenAPI specification and how to create them
  • Other interactive documentation platforms

Where to find more information

What engineers want in documentation

Why interactivity with API docs?

Swagger UI Petstore Demo

OpenAPI specification

Objects in OpenAPI spec

  • openapi
  • info
  • servers
  • paths
  • components
  • security
  • tags
  • externalDocs

Petstore sample spec | Spec reference

Swagger Editor

Forms simplify authoring

Standardized terminology

Not just for interactive documentation

Tutorial for building OpenAPI spec doc

(See also Peter Gruenbaum's resources (STC preso and Udemy course)

Tools can programmatically process the spec

Swagger UI

Swagger UI is open-source and can easily be hosted on a web server.


SwaggerHub is considered the commercial version of Swagger.


Stoplight builds many services around the OpenAPI spec file. Demo: Threat Stack.


Import OpenAPI spec or build from within. Demo: Box API.


Plug in OpenAPI spec and build. Demo: Cheese Store


A different UI for each programming language.

Integration challenges


The end

Tom Johnson
[email protected]


Some graphics by: and the Noun Project.