OpenAPI and Swagger

By Tom Johnson / @tomjohnson
idratherbewriting.com

Slides available at
idratherbewriting.com//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"