Forum Discussion

nneul's avatar
nneul
Occasional Visitor
3 years ago

How to document an array that is a sequence of specific data types?

Note - I've seen the various examples covering alternative data types, such as this discussion:

    https://community.smartbear.com/t5/Swagger-Open-Source-Tools/How-to-document-multiple-data-types-array-in-OpenAPI-Definition/td-p/224709

 

That's not what I'm looking for. I'm wanting to be able to document an existing API (if I could change it, it would be much easier and this would not be an issue, but that's not scope) that has a response of this form:

 

   [  statuscode_integer, statusmsg_string, zero_or_more_strings ]

 

i.e. 

 

  [ 0, "ok", "user1", "user2", "userN" ]

  [ 1, "failed to look up" ]

 

I'm looking for something like a "sequence" type:

 

  type: sequence
    items:
      - oneOf: 
           description: status code
           type: integer
      - oneOf:
          description: status message
          type: string
      - zeroOrMoreOf:
          description: list of matching users
          type: string

 

That obviously isn't valid - but is there any way to represent this without just resorting to a typeless array with an unstructured example?

 

Note - this is just one example for a particular API function. There are others that would be [int,string,{object}] or [int, string, [array]] etc - key is that the response is a sequence of explicit types.