OpenAPI 3.x.x having different response with the change of Optional Parameters

Question

I am trying to create the OAS Swagger documentation for an existing API where the response for the API is changing on the basis of Query parameter. I am struggling to document this in a developer friendly way, so need some assistance. Below is the complete scenario for your reference.

EndPoint 1 : /order?expand=false

/order?expand=false

{
    "orderNo": "12345",
    "orderDetail": "Description of Order",
    "orderMarket": {
        "id": "UK"
    },
    "brandOrderStatus": {
        "id": "LLA"
    }
}

Endpoint 2 : /order?expand=true

{
    "orderNo": "12345",
    "orderDetail": "Description of Order",
    "orderMarket": {
        "id": "UK",
        "descr": "United Kingdom",
        "lang": "en-GB"
    },
    "brandOrderStatus": {
        "id": "LLA",
        "descr": "Some Status Description",
        "lang": "en-GB"
    }
}

Endpoint 3 : /order?expand=true&include=feature

{
    "orderNo": "12345",
    "orderDetail": "Description of Order",
    "orderMarket": {
        "id": "UK",
        "descr": "United Kingdom",
        "lang": "en-GB"
    },
    "brandOrderStatus": {
        "id": "LLA",
        "descr": "Some Status Description",
        "lang": "en-GB"
    }
    "_embedded": {
        "features": [
            {
                "id": "AJS",
                "type": "FeatureType",
                "descr": "FeatureDescription",
                "prices": [
                    {
                        "type": "msrpNetPrice",
                        "amount": 0.00,
                        "currency": "GBP"
                    }
                ],
                "group": "null"
            }
        ]
    }
}

I tried using OneOf, but don't really think that will work in this case as the structure is changing with every optional parameter.

Any thoughts as how this can be documented in Swagger documentation ? Or any other idea to get this documented.

Answer 1

The most straight forward solution to something like this depends on how you expect to use the OpenAPI description. If it's for documentation purposes only, you can use examples and define those accordingly. If you want to use it for code-gen, using anyOf may be the better option to define the expected payload.

Unfortunately, OpenAPI doesn't have a terrific way to document "scenarios" like this. (if I send these query params, this is the response). None of the examples will explicitly correspond to the anyOf schema representations. You need to define the entire response either with the full representation or with a anyOf schema design.

Here's with examples and anyOf response schemas

{
  "openapi": "3.0.3",
  "info": {
    "title": "test",
    "version": "1.0.0"
  },
  "servers": [],
  "paths": {
    "/order": {
      "get": {
        "summary": "stack",
        "parameters": [
          {
            "$ref": "#/components/parameters/expand"
          },
          {
            "$ref": "#/components/parameters/include"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {},
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/order"
                    },
                    {
                      "$ref": "#/components/schemas/orderDetail"
                    },
                    {
                      "$ref": "#/components/schemas/orderDetailWithFeatures"
                    }
                  ]
                },
                "examples": {
                  "expand_false": {
                    "$ref": "#/components/examples/expand_false"
                  },
                  "expand_true": {
                    "$ref": "#/components/examples/expand_true"
                  },
                  "expand_with_features": {
                    "$ref": "#/components/examples/expand_with_features"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "expand": {
        "name": "expand",
        "description": "expands the response schema with more details",
        "in": "query",
        "schema": {
          "type": "boolean"
        }
      },
      "include": {
        "name": "include",
        "description": "expands the response schema with more details",
        "in": "query",
        "schema": {
          "type": "string",
          "enum": [
            "feature"
          ]
        }
      }
    },
    "schemas": {
      "order": {
        "type": "object",
        "properties": {
          "orderNo": {
            "type": "string"
          },
          "orderDetail": {
            "type": "string"
          },
          "orderMarket": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              }
            }
          },
          "brandOrderStatus": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              }
            }
          }
        }
      },
      "amountType": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string"
          },
          "amount": {
            "type": "number"
          },
          "currency": {
            "type": "string",
            "enum": [
              "USD",
              "GBP",
              "EUR"
            ]
          }
        }
      },
      "lang-descType": {
        "type": "object",
        "properties": {
          "lang": {
            "type": "string"
          },
          "descr": {
            "type": "string"
          }
        }
      },
      "features": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "type": {
              "type": "string"
            },
            "descr": {
              "type": "string"
            },
            "prices": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/amountType"
              }
            },
            "group": {
              "type": "string"
            }
          }
        }
      },
      "orderDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/order"
          },
          {
            "type": "object",
            "properties": {
              "orderMarket": {
                "allOf": [
                  {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string"
                      }
                    }
                  },
                  {
                    "$ref": "#/components/schemas/lang-descType"
                  }
                ]
              },
              "brandOrderStatus": {
                "allOf": [
                  {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string"
                      }
                    }
                  },
                  {
                    "$ref": "#/components/schemas/lang-descType"
                  }
                ]
              }
            }
          }
        ]
      },
      "orderDetailWithFeatures": {
        "allOf": [
          {
            "$ref": "#/components/schemas/orderDetail"
          },
          {
            "type": "object",
            "properties": {
              "_embedded": {
                "type": "object",
                "properties": {
                  "features": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/features"
                    }
                  }
                }
              }
            }
          }
        ]
      }
    },
    "examples": {
      "expand_false": {
        "value": {
          "orderNo": "12345",
          "orderDetail": "Description of Order",
          "orderMarket": {
            "id": "UK"
          },
          "brandOrderStatus": {
            "id": "LLA"
          }
        }
      },
      "expand_true": {
        "value": {
          "orderNo": "12345",
          "orderDetail": "Description of Order",
          "orderMarket": {
            "id": "UK",
            "descr": "United Kingdom",
            "lang": "en-GB"
          },
          "brandOrderStatus": {
            "id": "LLA",
            "descr": "Some Status Description",
            "lang": "en-GB"
          }
        }
      },
      "expand_with_features": {
        "value": {
          "orderNo": "12345",
          "orderDetail": "Description of Order",
          "orderMarket": {
            "id": "UK",
            "descr": "United Kingdom",
            "lang": "en-GB"
          },
          "brandOrderStatus": {
            "id": "LLA",
            "descr": "Some Status Description",
            "lang": "en-GB"
          },
          "_embedded": {
            "features": [
              {
                "id": "AJS",
                "type": "FeatureType",
                "descr": "FeatureDescription",
                "prices": [
                  {
                    "type": "msrpNetPrice",
                    "amount": 0.00,
                    "currency": "GBP"
                  }
                ],
                "group": "null"
              }
            ]
          }
        }
      }
    }
  }
}