Swagger 2.0 - come rendere necessario "uno o l'altro" parametro?

Question

Ho una risorsa spavalderia 2.0 definita di seguito. Come posso rendere necessario "param1 o param2"? Il chiamante deve passare param1 o 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 

Answer 1

OpenAPI (fka Swagger) Le specifiche non supportano i parametri condizionali o mutuamente esclusivi (di qualsiasi tipo).

V'è una richiesta di funzionalità aperto:
Support interdependencies between query parameters

Answer 2

specifica La Swagger non supporta requisito condizionale o inclusione/esclusione di parametri.

Quello che suggerirei è di indicare chiaramente nella descrizione le regole per l'inclusione/esclusione dei parametri di query. Quindi, utilizzando un framework di validazione, che dipende dalla lingua dell'utente (ad es. Javax.validation per Java, restify-validation per restify, ecc.), Convalidare i parametri di conseguenza.

Answer 3

Nella sezione dei parametri dipendenze dei documenti Describing Parameters Swagger:

Swagger non supporta dipendenze parametri ei parametri reciprocamente esclusivi. C'è una richiesta di funzionalità aperta a https://github.com/OAI/OpenAPI-Specification/issues/256.

A partire da giugno 2017, tale numero ha avuto 21 revisioni, diventando così il terzo problema più aggiornato del progetto.

Answer 4

Lo scenario specifico in questa questione - una richiesta POST/PUT/PATCH con un corpo form-data che contiene sia param1 o param2 - può essere definito utilizzando OpenAPI 3.0 e 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 

Nota per Swagger Utenti dell'interfaccia utente: UI di dati di modulo e rendering di esempio per gli schemi oneOfare not available per le definizioni di OpenAPI 3.0.