Skip to content
This repository has been archived by the owner on Sep 14, 2022. It is now read-only.

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

Closed
erictheise opened this issue Dec 7, 2015 · 6 comments
Closed

Comments

@erictheise
Copy link
Contributor

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
Copy link
Contributor

fehguy commented Dec 7, 2015

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
Copy link

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

@erictheise
Copy link
Contributor Author

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

@keanerickson
Copy link

keanerickson commented Aug 24, 2016

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
Copy link
Contributor

fehguy commented Aug 24, 2016

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
Copy link

OK, thanks for the info.

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants