Harnessing the Chi of Swagger in Your API Docs

TC Dojo, open session. January 9, 2017

Created by Tom Johnson / @tomjohnson

More detail

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


What engineers want...

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

      description: Returns all pets from the system that the user has access to
      operationId: findPets
        - application/json
        - application/xml
        - text/xml
        - text/html
        - name: tags
          in: query
          description: tags to filter by
          required: false
          type: array
            type: string
          collectionFormat: csv
        - name: limit
          in: query
          description: maximum number of results to return
          required: false
          type: integer
          format: int32
          description: pet response
            type: array
              $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

Configuring Swagger UI

  1. Download Swagger UI
  2. Extract and pull out dist folder.
  3. Open index.html file and edit url value to swagger spec.
  4. 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 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:



Tom Johnson
[email protected]