Swagger

Harnessing the Chi of Swagger in Your API Docs

TC Dojo, open session. January 9, 2017

Created by Tom Johnson / @tomjohnson
idratherbewriting.com

More detail

For a written version of this presentation, see Implementing Swagger (OpenAPI specification) with your REST API documentation in my API doc course.

Introduction

Image by Gulheim from The Noun Project

About Swagger

Swagger is a specification format for describing REST APIs. From this spec, you can create interactive documentation, automate test scripts, and more. Swagger is now called OpenAPI Specification.

Sample spec


paths:
  /pets:
    get:
      description: Returns all pets from the system that the user has access to
      operationId: findPets
      produces:
        - application/json
        - application/xml
        - text/xml
        - text/html
      parameters:
        - name: tags
          in: query
          description: tags to filter by
          required: false
          type: array
          items:
            type: string
          collectionFormat: csv
        - name: limit
          in: query
          description: maximum number of results to return
          required: false
          type: integer
          format: int32
      responses:
        '200':
          description: pet response
          schema:
            type: array
            items:
              $ref: '#/definitions/pet'

The spec can be in either YAML or JSON formats.

Swagger editor

Manual or Automated?

Manual: You write the spec file by hand.
"Automated": You add annotations in your source code, and then generate the spec file.

Benefits of manual

The spec acts as a contract that developers write to.
You as a tech writer have total control.
Curse of knowledge makes devs write poor docs.

The spec as a contract

For developers, it’s very easy to jump in the code and just change code. And once you change the code, you introduce backwards incompatibilities, you can break other features without realizing it. But the spec is still there, it says no, you have to test this, you have to make sure it stays consistent. It is the contract, and by following it you know you’re not breaking backwards compatibility.

— Michael Stowe (Podcast: Spec-driven Development of REST APIs, with a focus on RAML -- interview with Michael Stowe)

Benefits of automated

Reduces doc drift.
Aligns devs with documentation creation and review.
Eliminates frustrations in getting YAML syntax correct.

Parsing the Swagger spec

The spec alone does nothing. You need a display framework, such as Swagger UI, to parse it.

Other frameworks to parse Swagger

How to use Swagger UI

Go to http://petstore.swagger.io/
Create a new pet (using POST /pet)
Retrieve your pet through the ID (using GET /pet/{petID})
Paste another swagger spec from this link into Explore.

Weather API Swagger

Weather by fyhao
Swagger spec
Use the Full Weather Data endpoint, with lat 37.3708853 and lng -122.0025719

Configuring Swagger UI

Download Swagger UI
Extract and pull out dist folder.
Open index.html file and edit url value to swagger spec.
Load index.html into Firefox and try out.

Learning the spec syntax

See OpenAPI Specification on Github. The documentation takes some getting used to.

SwaggerHub

SwaggerHub provides Cloud-based Swagger hosting, with team access + more

RAML: Another spec

RAML is a competing spec. Sample display: http://learnapidoc.com/raml/

Responses to Swagger documentation

Everyone loves the interactivity
Functions like quick reference guide
Taught me industry standard vocabulary for REST APIs
Powerful learning capabilities with hands-on exploration

Downsides to Swagger

REST APIs can't have complex request body parameters
Getting YAML syntax right is hell
Redundant with other documentation content
Requires test environment to protect customer data

Integrating Swagger into main doc

Can I integrate Swagger into the rest of my docs? No, but see these resources:

Questions?

Thanks!

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