Is it possible to return different schemas based on a query parameter?

[erictheise]

I would like to be able to document an API where /states returns a simple array of information, e.g.,

[
  {
    name: "Alabama",
    abbrev: "AL"
  },
  {
    name: "Alaska",
    abbrev: "AK"
  },
  {
    name: "Arizona",
    abbrev: "AZ"
  }
]

but /states?geo=true returns a GeoJSON FeatureCollection, e.g.,

{
  type: "FeatureCollection",
    features: [
      {
        type: "Feature",
        properties: {
          name: "Alabama",
          postal: "AL"
        },
        geometry: {
          type: "MultiPolygon",
          coordinates: [
            [
              [
                [
                  -88.0909724599999,
                  30.2446963560001
                ],
                [
                  -88.3112686839999,
                  30.2367617860001
                ],

...

but I can't see my way clear. If I'm reading this proposal correctly, it's not possible in the current spec. What is the "swagger way" of handling a situation like this?

[fehguy]

You are correct--changing the primary response type from object to array in the same http method is a bad idea. You can wrap your array inside an object:

{
  "results": [
    {
      "name": "Alabama",
      "abbrev": "AL"
    }
  ]
}

In fact, I'd suggest modeling your response like such:

{
  "results": [ ... ],
  "features": [ ... ]
}

and let the query param indicate inclusion of the response in the payload.

[keanerickson]

@fehguy What is this "features" property? I don't understand what you're proposing.

[erictheise]

@keanerickson, features, geometry, coordinates, etc., they're all part of the GeoJSON Format and were specific to my needs.

[keanerickson]

Ah, I missed that detail. I was hoping that what you described in the title could be done with swagger in general (different response schemas depending on a request parameter). I get the determinism aspect, but it's too bad that not all existing APIs can be described with swagger due in part to this.

[fehguy]

Well @keanerickson good and bad news. The bad news is that "describing all APIs" is not the scope of swagger, and if it were, the tooling would simply suck. Some things cannot be described in a reasonable manner, period.

The good news is that the 3.0 spec will support oneOf or anyOf which will allow you to have different response schemas. That will improve scope for modeling more APIs, not necessarily making them "good". But it will solve your concern.

[keanerickson]

OK, thanks for the info.