So I have done some hunting around online, and have been able to figure out how to use the enum tag in a swagger doc to specify a list of possible values for a field. However, in my current API what I need instead is to have a list of potential fields, each of which has a string value.
To be more precise, I have a POST request that sends JSON in the request body. As part of this request users need to send a single ID field. However, we accept multiple types of ID fields. So the request would look something like this:
{name:"name", product:"product", [FirstIdType, SecondIdType, ThirdIdType]:"ID Value"}
So I need to have the user submit a JSON that has a name, product, and one of FirstIdType, SecondIdType, or ThirdIdType. Technically it is required to have exactly one of those three ID types in the request, but I don't really mind if that isn't possible in the swagger doc. Noting it in the description for the field is fine.
The other constraint is that I can't really change the design at this point. The app has already been built using this design and changing it is out of my hands. Which means that I can't just make an array of ID Types and then choose one of them.
Here is the relevant bit from my swagger doc. The area that needs changed is the ID field. Any thoughts or directions on how to get that to go forward would be really appreciated.
definitions:
request_post:
description: (post) request schema
properties:
name:
type: string
product:
type: string
Id:
type: string
Instead of defining what optional fields can come on the path, you can label the fields that are required and make the rest variable by default.
http://swagger.io/specification/#parameterObject
required boolean Determines whether this parameter is mandatory. If the parameter is in "path", this property is required and its value MUST be true. Otherwise, the property MAY be included and its default value is false.