Parameter of type "associative array"

Let’s use the “pet store” application as example

Imagine that you can send multiple “find” requests in one. For that, you pass an array of associative arrays, which contain a list of integers

Text version:

criteria[0][status]: 1
criteria[0][tags]: 2,3
criteria[1][status]: 2
criteria[1][tags]: 4,5

POST /find HTTP/1.1
Host: petstore.com
Content-Type: application/x-www-form-urlencoded

criteria%5B0%5D%5Bstatus%5D=1&criteria%5B0%5D%5Btags%5D=2%2C3&criteria%5B1%5D%5Bstatus%5D=2&criteria%5B1%5D%5Btags%5D=4%2C5

How would you define that ?

I suggest the following syntax addition : adding a new property “indexType” to give the type of the keys in an array (default: integer, 0-based)

Example definition using this syntax

swagger: '2.0'
info:
  version: '1.0.0'
  title: Swagger Petstore (Simple)
  description: A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification
  termsOfService: http://helloreverb.com/terms/
  contact:
    name: Swagger API team
    email: [e-mail]
    url: http://swagger.io
  license:
    name: MIT
    url: http://opensource.org/licenses/MIT
host: petstore.swagger.wordnik.com
basePath: /api
schemes:
  - http
consumes:
  - application/json
produces:
  - application/json
paths:
  /pets/find:
    get:
      description: Returns multiple search query results at the same time
      operationId: findPets
      produces:
        - application/json
        - application/xml
        - text/xml
        - text/html
      parameters:
        - name: criteria
          in: query
          description: search criteria
          required: true
          type: array
          items:
            type: array
            indexType: searchCriteria
            uniqueItems: true
            items:
              type: array
              items:
                type: integer
          collectionFormat: csv
      responses:
        '200':
          description: pet response
          schema:
            type: array
            items:
              type: array
              $ref: '#/definitions/pet'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/errorModel'
definitions:
  searchCriteria:
    type: string
    enum:
    - tags
    - status
  pet:
    required:
      - id
      - name
    properties:
      id:
        type: integer
        format: int64
      name:
        type: string
      tag:
        type: string
  errorModel:
    required:
      - code
      - message
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string

[webron]

Technically, you can describe that today by naming the parameter date[gte] and setting the type to string.

[rkyoku]

Hi there,

Any news on that? Associative arrays are all over the place in APIs (at least then ones I worked/work on)

I suggest using the simple “keys” parameter:

name: pop
description: population by country
type: array
keys:
    type: string
    description: country code (2 characters)
items:
    type: integer
    description: population (in thousands)

Do you think it is feasible to add it? For now I am using “x-keys” with the same format, but it won’t display in the generated documentation (unless I’m mistaken)