OpenAPI - comment décrire les paramètres de requête?

Question

J'essaie de comprendre comment documenter deux de mes paramètres de requête dans OpenAPI.

Filtration

Mon filtrage suit les recommandations de JSON: API , qui prend par exemple la forme de:

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

La filterclé est un tableau associatif qui peut contenir une liste de noms de ressources dans mon API. La valeur attribuée à chaque clé de filtre est soit un identifiant unique, soit une liste d'identifiants séparés par des virgules.

Tri

Pour le tri, suit également la recommandation JSON: API , donc quelque chose comme ceci:

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

Le sortparamètre de requête reçoit la valeur d'un champ de tri ou d'une liste de champs de tri séparés par des virgules. Notez que le signe moins qui préfixe le heightchamp indique un tri décroissant.

Question

Comment représenter mon filtrage et mon tri dans OpenAPI ?

Par exemple, je ne suis pas sûr qu'il soit possible pour moi de spécifier que la clé de filtre est un tableau associatif ou qu'elle accepte une liste d'identifiants séparés par des virgules. Presque le même problème pour le tri: comment représenter une liste de champs de tri séparés par des virgules?

Answer 1

L'approche ci-dessous devrait aider

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

Une partie est similaire à la question partagée par @Helen. Cela vous permettra de l'utiliser comme dans l'image ci-dessous

Et la commande cURL respective

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

Vous pouvez également définir le filterparamètre de la manière ci-dessous

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

Cela entraînera une interface utilisateur plus complète comme ci-dessous

Ensuite, la demande cURL ressemble à ci-dessous

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

Et vous ne devriez probablement pas en avoir besoin anyOfcar il est lié à l'héritage pour les situations où une méthode peut retourner un objet de la classe de base ou de l'une de ses sous-classes.

Référez -vous à oneof-anyof-allof-not - Spécification OpenAPI pour plus d'informations à ce sujet.