Swagger 2.0 - comment faire de “l'un ou l'autre paramètre requis?

J'ai un swagger 2.0 ressource définie ci-dessous. Comment puis-je faire "param1 ou param2" nécessaire? L'appelant doit passer soit param1 ou param2.

/some/res:
put:
  summary: some resource
  responses:
    200:
      description: Successful response
      schema:
        $ref: '#/definitions/SomeResponse'
  parameters:
    - name: param1
      type: string
      description: param1
      in: formData
      required: false
    - name: param2
      type: string
      description: param2
      in: formData
      required: false
InformationsquelleAutor Vineet Bhatia | 2015-04-17
  1. 45

    OpenAPI (autrefois connue sous la dénomination Swagger) Spécification ne prend pas en charge conditionnelle ou mutuellement exclusifs paramètres (de tout type).

    Une demande de fonctionnalité:

    Soutenir les interdépendances entre les paramètres de la requête

    InformationsquelleAutor Ron
  2. 6

    Dans le Paramètre de la section des Dépendances de la Décrivant Les Paramètres Swagger docs:

    Swagger ne prend pas en charge le paramètre de dépendances et mutuellement exclusifs paramètres. Une demande de fonctionnalité à https://github.com/OAI/OpenAPI-Specification/issues/256.

    En juin 2017, cette question a 21 upvotes, faisant d'elle la troisième plus upvoted question dans le projet.

    InformationsquelleAutor Trenton
  3. 5

    Le scénario spécifique dans cette question – un POST/PUT/PATCH demande avec un formulaire de données corps qui contient soit param1 ou param2 – peut être défini à l'aide de OpenAPI 3.0 et oneOf:

    openapi: 3.0.0
...

paths:
  /some/res:
    put:
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              oneOf:
                - type: object
                  properties:
                    param1:
                      type: string
                  required:
                    - param1
                  additionalProperties: false
                - type: object
                  properties:
                    param2:
                      type: string
                  required:
                    - param2
                  additionalProperties: false

    Note pour Swagger INTERFACE utilisateurs: formulaire de données de l'INTERFACE utilisateur et l'exemple de rendu pour oneOf schémas ne sont pas disponibles pour OpenAPI 3.0 définitions encore.

    • Comment sur l'utilisation de oneOf contre les paramètres de la requête à la place du schéma corporel? Je suppose que ce n'est toujours pas pris en charge?
    • Je ne suis pas sûr, c'est difficile à dire sans voir le spec. Si quelque chose ne fonctionne pas dans le Style de l'INTERFACE utilisateur, je vous suggère de vous de déposer un problème ici: github.com/swagger-api/swagger-ui/issues
    InformationsquelleAutor Helen
  4. 3

    L'Arrogance spécification ne prend pas en charge conditionnelle exigence ou d'exclusion/inclusion de paramètres.

    Ce que je suggère, c'est d'indiquer clairement dans la description de vos règles d'inclusion/exclusion des paramètres de la requête. Puis à l'aide d'un cadre de validation, qui dépend de la langue (c'est à dire javax.la validation de Java, restify de validation pour restify, etc.), valider les paramètres en conséquence.

    InformationsquelleAutor Gene Ames