Swagger Spec: An Embarrassment of Riches

Swagger Spec is a great way to define and document API projects. Your code and documentation live and ship together, allowing for rapid documentation and development. However, you might say it’s too good.

As your team and APIs using Swagger grow, so too do the challenges of wrangling that giant spec without breaking your APIs or driving your developers bonkers. Unfortinately, tools like the Swagger Validator start to break down for large, real worls specs ¹. Here are some lessons I learned productionizing such large specs ².

1. Use YAML, Not JSON

JSON is hard to read and easy to corrupt in large file sizes. YAML has:

• Better readability
• Intellij, Atom, and SubLime editor support
• IDE (and vim) schema auto complete

2. Break Up Your Spec

Use the $ref includes functionality to compose multiple files into one spec. Break your spec into relevant sub sections (e.g. by entity type, department, etc). This will:

• Reduce checkin conflicts between developers
• Increase readability and maintainabilty
• More easily isolate spec errors

3. DRY: Don’t Repeat YAML

Swagger allows reuse of enums, so don’t repeat them in the GET & POST endpoints, and inside the data objects. $ref references work for enums just like other Swagger object references.

paths:
  /widgets:
    get:
      parameters:
      - in: query
        name: shape
        required: true
        schema:
          $ref: '#/components/schemas/Shape'
      responses:
        '200':
          description: OK
components:
  schemas:
    Shape:
      type: string
      enum:
        - round
        - square
        - triangle

4. Automate Swagger Spec Validation

Preemptively validate your spec, rather than wait until your API fails to start or object mapping errors throw 500’s in production.

See my Automating Swagger Spec validation post on using Yelp’s Swagger Spec Validator.