Swagger - How to write common response field?

Question

I have several APIs, and all of them return JSON with a boolean field named success.

API 1 {"success": true, "data": "some data"}

API 2 {"success": false, "error": "error message"}

Can I write its swagger 2.0 document with something like a template, so I don't need to copy and paste the success field part in each API like this?

  responses:
    200:
      schema:
        properties:
          success:
            type: boolean
             description: true if the request is successful.
          data:
             ...

and

  responses:
    200:
      schema:
        properties:
          success:
            type: boolean
             description: true if the request is successful.
          error:
             ...

Thanks!

fehguy fehguy · Accepted Answer · 2016-11-09T05:44:48

Yes, use allOf for the common fields:

responses:
  200:
    schema:
      allOf:
        - $ref: '#/definitions/common'
        - properties:
            data:
            # your details here

definitions:
  Common:
    type: object
    properties:
      success:
        type: boolean
         description: true if the request is successful.

Also:

      schema:
        allOf:
          - $ref: '#/definitions/Common'
          - properties:
              data:
                $ref: '#/definitions/Another'

Swagger - How to write common response field?

1 Answers