Support for Either

[ikitommi]

hi.

Would like to be able present a type of Either[Dog,Cat] (or in clojure (either Dog, Cat, Moose) in the Spec. Quite common construct in the FP land. Would be like a enum, but with values of any type.

Currently such a thing could be presented as a complex type with optional fields for all the value => at least the swagger-ui would be able to generate sample models (with all possible alternatives in place) for it. Not perfect, but ~works. Requires also special coercion in the server side to map back into Either.

http://www.scala-lang.org/api/2.11.0/index.html#scala.util.Either

https://github.com/Prismatic/schema/blob/master/test/cljx/schema/core_test.cljx#L194-L203

[ikitommi]

... in JSON Schema this would be implemented most likely with oneOf like:

{
  "oneOf": [
    { "$ref": "Cat" },
    { "$ref": "Dog" }
  ]
}

[webron]

Okay, in Swagger 2.0 we explicitly decided not to support this. There are various issues with supporting it ranging from how deterministic such an API is to can most common development languages support this feature easily.

I'm closing this issue for now, but marking it as a proposal for the next version of the spec, so that we may revisit this decision.

[ahultgren]

I wonder, if I have a resource which sends a response as an array that contains both say articles and ads, how would i define such a response in swagger? Combining all properties in one response object is really ugly and kinda makes validation based on the spec useless. I think oneOf would be a good solution for this case, unless I've missed another way of doing it?

[webron]

We thrive to describe deterministic APIs. Sending a single array of both articles and ads makes it that much more difficult to process, especially for strongly-typed languages, so we don't support it. If we can find an elegant way to do it, we'll be more than happy to add support for it.

[jphastings]

@webron Which languages would be most important to support? I mentioned on IRC the use case of GeoJSON, which I think is an important structure to be able to validate:

{
  "type": "Point",
  "coordinates": [-3.0107731, 16.7733758]
}

{
  "type": "LineString",
  "coordinates": [[-3.0107731, 16.7733758], [-101.8314831,35.2090451]]
}

[davidsklar]

I am new to Swagger and have already encountered several areas where this would be useful. With respect to the deterministic-API goal, what are popular-enough strongly-typed languages that would have great difficulty processing, e.g. a heterogenous collection? (As long as the possible types of the collection were explicitly enumerated and were defined (in swagger and the other language) in an appropriate way to indicate a relationship (parent-class/child-class, etc) that played nice with the type system.

[stevage]

I think I understand the reasons for discouraging people from designing APIs where different types of objects can appear in the same place. (The term "non-deterministic API" doesn't seem quite right to me though.)

But anyway, it's a bit of a problem for documenting existing APIs (or GeoJSON, above). I'm working on one at the moment where a certain response contains an array of "stops" and "lines", where each is basically:

{
  "type": "stop", # or "line"
  "result": {
     # other properties depend on type
  }
}

Obviously it's possible to implement this in Swagger but it's pretty hacky and requires duplication and having to explain in words what's going on.

[webron]

This is not about API design only, this is also related to the ability to provide support for it in the various tools we offer around Swagger. Since there is a workaround for some cases, it may be good enough for now. That said. it does not mean it will not be considered for the next version, we just need to do it wisely.