OpenAPI and Swagger

By Tom Johnson / @tomjohnson
idratherbewriting.com


Slides available at
idratherbewriting.com//learnapidoc/slides/openapi_and_swagger.html

Engineers want to push buttons

Designing for opportunistic behavior

"...opportunistic developers in our test started the first task with some example code from the documentation which they then modified and extended. Once a task was completed, the piece of code that solved the task was used as starting point for the next task.... Developers in this group worked in a highly task-driven manner, but also tried things that were not related to the task, but possibly helped them to build a broader understanding of the API in passing." — Meng et al

Interactivity enhances learning

Swagger UI Petstore Demo

Activity 4a: Explore Swagger UI through the Petstore Demo

The OpenAPI standard for REST APIs

Objects in OpenAPI spec

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

Petstore sample spec | Spec reference

OpenAPI spec at a glance


paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      tags:
        - pets
      parameters:
        - name: limit
          in: query
          description: How many items to return at one time (max 100)
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: An paged array of pets
          headers:
            x-next:
              description: A link to the next page of responses
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pets"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
            

YAML syntax

Swagger Editor

Stoplight Studio - A GUI Editor

Spec-first development philosophy

Spec uses extend beyond docs

Activity 4b: Create an OpenAPI specification using Stoplight Studio

Forms simplify authoring

Specs standardize terms

Tools to render the spec

Redoc

Activity 4c: Create a Redoc display

Swagger UI

Activity 4d: Create a Swagger UI display

Readme

Demo: MixPanel API

DeveloperHub.io

Demo: Dev Hub Help

Integration challenges

Questions?