Avoid boilerplate in Swagger 2.0

Question

My APIs respect the conventional status codes and I have found myself repeating the same text in the responses part of my api definition

404:
          description: The resource doesn't exist
          schema:
            $ref:   '#/definitions/Error'
default:
          description: An unexpected error has occurred
          schema:
            $ref:   '#/definitions/Error'

A similar problem I also encounter is that I can't factor out enum properties and parameters. Can my Swagger code become more dry?

Arnaud Lauret Arnaud Lauret · Accepted Answer · 2016-06-13T17:18:06

Yes, your code can become far more dry: the OpenAPI (fka. Swagger) specification offers many ways of factoring things, including responses, parameters and enums.

Reusable responses

You can define reusable response almost the same way you defined Errorin your example.

First add response, for example Standard404, definition in responses on root level

responses:
  Standard404:
    description: The resource doesn't exist
    schema:
      $ref: '#/definitions/Error'

Then, use it with a $ref : '#/responses/Standard404' for 404 status code in responses on any operation

responses:
  404:
    $ref: '#/responses/Standard404'

Reusable parameters

For reusable parameters, it's the same thing.

First add a parameter, for example ID, definition in parameters on root level:

parameters:
  ID:
    name: id
    in: path
    required: true
    type: string

Then use it in any list of parameters with a $ref: '#/parameters/ID'. Pro tip: parameters can be defined on operation level but also on path level:

  /other-resources/{id}:
    get:
      parameters:
        - $ref: '#/parameters/ID'

 /resources/{id}:
    parameters:
      - $ref: '#/parameters/ID'

Reusable enums

All you need to do is to define a definition of type string (or integer or number) with the enum:

SomeValueWithEnum:
    type: string
    enum:
      - a value
      - another value

And then use it as many times as you wish like this:

 Resource:
    properties:
      dummyProperty:
        $ref: '#/definitions/SomeValueWithEnum'

Full example

Here's a full example for these 3 use cases:

swagger: '2.0'

info:
  version: 1.0.0
  title: API
  description: Reusable things example

paths:

  /resources:
    post:
      responses:
        200:
          description: OK
        default:
          $ref: '#/responses/Default'

  /resources/{id}:
    parameters:
      - $ref: '#/parameters/ID'
    get:
      responses:
        200:
          description: OK
        404:
          $ref: '#/responses/Standard404'
        default:
          $ref: '#/responses/Default'
    delete:
      responses:
        200:
          description: OK
        404:
          $ref: '#/responses/Standard404'
        default:
          $ref: '#/responses/Default'

  /other-resources/{id}:
    get:
      parameters:
        - $ref: '#/parameters/ID'
      responses:
        200:
          description: OK
        404:
          $ref: '#/responses/Standard404'
        default:
          $ref: '#/responses/Default'

definitions:
  Error:
    properties:
      message:
        type: string

  SomeValueWithEnum:
    type: string
    enum:
      - a value
      - another value

  Resource:
    properties:
      dummyProperty:
        $ref: '#/definitions/SomeValueWithEnum'

  AnotherResource:
    properties:
      anotherDummyProperty:
        $ref: '#/definitions/SomeValueWithEnum'

parameters:
  ID:
    name: id
    in: path
    required: true
    type: string

responses:
  Standard404:
    description: The resource doesn't exist
    schema:
      $ref: '#/definitions/Error'
  Default:
    description: An unexpected error has occurred
    schema:
      $ref:   '#/definitions/Error'

More about this You should read this tutorial (disclosure: I wrote it) and the OpenAPI Specification.

Avoid boilerplate in Swagger 2.0

1 Answers