OpenAPI and Swagger

By Tom Johnson / @tomjohnson
idratherbewriting.com

Slides available at
idratherbewriting.com/openapi-and-swagger

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

idratherbewriting.com/learnapidoc

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

SwaggerHub is considered the commercial version of Swagger.

Stoplight

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

Readme

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

Spectacle

Plug in OpenAPI spec and build. Demo: Cheese Store

APIMATIC

A different UI for each programming language.

Integration challenges

Questions?

The end

Tom Johnson
— idratherbewriting.com
— @tomjohnson
— [email protected]

Credits

Some graphics by: Vecteezy.com and the Noun Project.