web-dev-qa-db-fra.com

Comment définir des paramètres de requête mutuellement exclusifs dans Swagger (OpenAPI)?

J'ai une série de paramètres dans Swagger comme celui-ci

                    "parameters": [
                    {
                        "name": "username",
                        "description": "Fetch username by username/email",
                        "required": false,
                        "type": "string",
                        "paramType": "query"
                    },
                    {
                        "name": "site",
                        "description": "Fetch username by site",
                        "required": false,
                        "type": "string",
                        "paramType": "query"
                    },
                    {
                        "name": "survey",
                        "description": "Fetch username by survey",
                        "required": false,
                        "type": "string",
                        "paramType": "query"
                    }
                ],

Un paramètre DOIT être rempli mais peu importe lequel, les autres peuvent être laissés en blanc. Existe-t-il un moyen de représenter cela dans Swagger?

swaggerswagger-uiopenapi
32
lorless

Malheureusement, cela n'est actuellement pas possible dans Swagger. "requis" n'est qu'un booléen et il n'y a aucun moyen de représenter les interdépendances entre les paramètres.

Le mieux que vous puissiez faire est d'indiquer clairement les exigences dans les descriptions des paramètres et de mettre également une description personnalisée de 400 demandes incorrectes dans le même sens.

(Il y a un peu de discussion sur https://github.com/swagger-api/swagger-spec/issues/256 sur les manières possibles de l'implémenter dans la prochaine version de Swagger)

11
Ruaidhri Primrose

Qu'en est-il de la modification de la conception de votre API? Actuellement, vous avez une méthode, 3 paramètres. Si je comprends bien, l'utilisateur doit toujours fournir exactement un paramètre et les deux autres doivent être désactivés.

Pour moi, l'API serait plus utilisable avec trois points de terminaison - comme

/user/byName?name=
/user/bySite?name=
/user/bySurvey?name=
7
Bartosz Bilicki

Des paramètres mutuellement exclusifs sont possibles (en quelque sorte) dans OpenAPI 3.0 :

  • Définissez les paramètres mutuellement exclusifs comme propriétés d'objet et utilisez oneOf ou maxProperties pour limiter l'objet à une seule propriété.
  • Utilisez la méthode de sérialisation des paramètres style: form et explode: true, afin que l'objet soit sérialisé en ?propName=value.

Un exemple utilisant les contraintes minProperties et maxProperties:

openapi: 3.0.0
...
paths:
  /foo:
    get:
      parameters:
        - in: query
          name: filter
          required: true
          style: form
          explode: true
          schema:
            type: object
            properties:
              username:
                type: string
              site:
                type: string
              survey:
                type: string
            minProperties: 1
            maxProperties: 1
            additionalProperties: false

Utilisation de oneOf:

      parameters:
        - in: query
          name: filter
          required: true
          style: form
          explode: true
          schema:
            type: object
            oneOf:
              - properties:
                  username:
                    type: string
                required: [username]
                additionalProperties: false
              - properties:
                  site:
                    type: string
                required: [site]
                additionalProperties: false
              - properties:
                  survey:
                    type: string
                required: [survey]
                additionalProperties: false

Une autre version utilisant oneOf:

      parameters:
        - in: query
          name: filter
          required: true
          style: form
          explode: true
          schema:
            type: object
            properties:
              username:
                type: string
              site:
                type: string
              survey:
                type: string
            additionalProperties: false
            oneOf:
              - required: [username]
              - required: [site]
              - required: [survey]

Notez que Swagger UI et Swagger Editor ne prennent pas encore en charge les exemples ci-dessus (en mars 2018). Ce problème semble couvrir la partie de rendu des paramètres.


Il existe également une proposition ouverte dans le référentiel de spécifications OpenAPI pour prendre en charge les interdépendances entre les paramètres de requête . moyen de définir de tels scénarios.

4
Helen

Une alternative consiste à passer un paramètre de type de filtre avec une énumération et une valeur de filtre avec la valeur à utiliser.

Exemple sur: https://app.swaggerhub.com/api/craig_bayley/PublicAPIDemo/v1

Il peut être requis ou non, selon votre choix. Cependant, si l'un est requis, ils devraient l'être tous les deux.

1
Craig Bayley