OpenAPI - como descrever os parâmetros de consulta?

Question

Estou tentando descobrir como documentar dois dos meus parâmetros de consulta no OpenAPI.

Filtrando

Minha filtragem segue as recomendações de JSON: API , que assume a forma de, por exemplo:

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

A filterchave é uma matriz associativa que pode conter uma lista definida de nomes de recursos em minha API. O valor atribuído a cada chave de filtro é um único id ou uma lista de ids separados por vírgulas.

Ordenação

Para classificação também segue a recomendação JSON: API , então algo assim:

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

O sortparâmetro de consulta é atribuído ao valor de um campo de classificação ou lista de campos de classificação separados por vírgulas. Observe que o sinal de menos que antecede o heightcampo indica uma classificação decrescente.

Questão

Como eu represento minha filtragem e classificação no OpenAPI ?

Por exemplo, não tenho certeza se é possível especificar que a chave de filtro é uma matriz associativa ou que aceita uma lista de ids separados por vírgula. Quase o mesmo problema para classificação: como representar uma lista separada por vírgulas de campos de classificação?

Answer 1

A abordagem abaixo deve ajudar

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

Parte disso é semelhante à pergunta que @Helen compartilhou. Isso permitirá que você use como na imagem abaixo

E o respectivo comando cURL

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

Você também pode definir o filterparâmetro da maneira abaixo

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

Isso fará com que a IU seja mais abrangente conforme abaixo

Em seguida, a solicitação cURL tem a seguinte aparência

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: */*"

E você provavelmente não deve precisar anyOf, pois está relacionado à herança para situações em que um método pode retornar um objeto da classe base ou qualquer uma de suas subclasses.

Consulte oneof-any-allof-not - OpenAPI Specification para obter mais informações.