# Swagger 2

OpenApi 3.0 (opens new window) has many improvements over Swagger 2 (opens new window). Here are a few which affect the Spike API, along with the workarounds which we have employed.

# 1. no support for oneOf

OpenApi 3.0 has oneOf (opens new window). This allows you to describe REST-ful endpoints which have a range of inputs (request params) or outputs (responses). Swagger 2.0 did not have this.

# 1.1 Workaround

just take first schema

# 1.2 How this impacts the Spike Swagger 2.0 API spec

/pdf can produce 5 successful output schemas:

/* OpenApi 3.0.1 */
{
  "responses": {
    "200": {
      "description": "see schemas: outputs-*",
      "content": {
        "application/json": {
          "schema": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/outputs-pdf-success-bank-statement-no-balance"
              },
              {
                "$ref": "#/components/schemas/outputs-pdf-success-bank-statement-normal"
              },
              {
                "$ref": "#/components/schemas/outputs-pdf-success-credit-card-breakdown-multi-user"
              },
              {
                "$ref": "#/components/schemas/outputs-pdf-success-credit-card-breakdown"
              },
              {
                "$ref": "#/components/schemas/outputs-pdf-success-credit-card-simple"
              }
              /* ... */
            ]
          }
        }
      }
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

However the swagger2.0 spec only lists 1 possible output schema:

/* Swagger 2.0 */
{
  "responses": {
    "200": {
      "description": "see schemas: outputs-*",
      "schema": {
        "type": "object",
        "items": {
          "$ref": "#/definitions/outputs-pdf-success-bank-statement-no-balance"
        }
      }
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 2. Syntax improvements

There are various syntax improvements which help improve expressive capability and accuracy.

paths..responses & paths..produces consolidated under a single paths..responses
- This is a cleaner way to link the MIME type to the response - e.g. if 200 is an application/json and 500 is application/text you don't have to guess which produces entry matches
paths..parameters is replaced by paths..requestBody and has the same convention for expressing the MIME type so that it's consistent with the paths..responses