OpenAPI: ¿cómo describir los parámetros de consulta?

Question

Estoy tratando de averiguar cómo documentar dos de mis parámetros de consulta en OpenAPI.

Filtración

Mi filtrado sigue las recomendaciones de JSON: API , que toma la forma de, por ejemplo:

• ?filter[post]=1,2,3
• ?filter[post]=1,2,3&filter[author]=5

La filterclave es una matriz asociativa que puede contener una lista establecida de nombres de recursos en mi API. El valor asignado a cada clave de filtro es un ID único o una lista de ID separados por comas.

Clasificación

Para ordenar también sigue la recomendación JSON: API , algo como esto:

• ?sort=age
• ?sort=age,-height

Al sortparámetro de consulta se le asigna el valor de un campo de clasificación o una lista de campos de clasificación separados por comas. Tenga en cuenta que el signo menos que antepone el heightcampo indica una clasificación descendente.

Pregunta

¿Cómo represento mi filtrado y clasificación en OpenAPI ?

Por ejemplo, no estoy seguro de que sea posible para mí especificar que la clave de filtro es una matriz asociativa o que acepta una lista de identificadores separados por comas. Casi el mismo problema para la clasificación: ¿cómo representar una lista de campos de clasificación separados por comas?

Answer 1

El siguiente enfoque debería ayudar

parameters:
  - in: query
    name: fields
    style: deepObject
    allowReserved: true
    schema:
      type: object
      properties:
        post:
          type: string
        author:
          type: string
  - in: query
    name: sort
    schema:
      type: array
      items:
        type: string
        enum:
          - age
          - height

Una parte es similar a la pregunta que compartió @Helen. Le permitirá usarlo como en la imagen de abajo

Y el comando cURL respectivo

curl -X GET "https://editor.swagger.io/user?filter[post]=1,2&filter[author]=3,4&sort=age&sort=height" -H  "accept: */*"

También puede definir el filterparámetro de la siguiente manera

parameters:
  - in: query
    name: filter
    style: deepObject
    allowReserved: true
    schema:
      type: object
      properties:
        post:
          type: array
          items:
            type: string
        author:
          type: array
          items:
            type: string

Esto dará como resultado que la interfaz de usuario sea más completa como se muestra a continuación

Entonces la solicitud cURL se ve a continuación

curl -X GET "https://editor.swagger.io/user?filter[post]=1&filter[post]=2&filter[author]=3&filter[author]=4&sort=age&sort=height" -H  "accept: */*"

Y probablemente no debería necesitarlo, anyOfya que está relacionado con la herencia para situaciones en las que un método puede devolver un objeto de la clase base o cualquiera de su subclase.

Consulte una de las especificaciones de OpenAPI para obtener más información al respecto.