Wie definieren sich gegenseitig ausschließende Abfrageparameter in Swagger (OpenAPI)?

Question

Ich habe eine Reihe von Parametern in Swagger wie diese

    "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" 
        } 
       ], 

Ein Parameter ausgefüllt werden muss, aber es spielt keine Rolle, was man kann die anderen leer gelassen werden. Gibt es eine Möglichkeit, dies in Swagger zu repräsentieren?

Answer 1

Leider ist dies in Swagger derzeit nicht möglich. "required" ist nur ein boolescher Wert und es gibt keine Möglichkeit, Abhängigkeiten zwischen Parametern darzustellen.

Das Beste, was Sie tun können, ist, die Anforderungen in den Parameterbeschreibungen zu verdeutlichen und eine benutzerdefinierte 400 Bad Request-Beschreibung in die gleiche Richtung zu schreiben.

(Es gibt ein bisschen Diskussion auf https://github.com/swagger-api/swagger-spec/issues/256 über mögliche Wege, dies in der nächsten Version von Swagger Implementierung)

Answer 2

Was ist mit Ihrem API-Design zu ändern? Derzeit haben Sie eine Methode, 3 Parameter. Wenn ich es gut verstehe, muss der Benutzer immer genau einen Parameter angeben, und zwei verbleibende müssen deaktiviert sein.

für mich API wären verwendbar mit drei Endpunkten -ähnlichen

/user/byName?name= 
/user/bySite?name= 
/user/bySurvey?name= 

Answer 3

Eine Alternative ist in einem Filtertyp-Parametern mit einem ENUM passieren, und ein Filterwert mit dem Wert zu verwenden.

Beispiel an: https://app.swaggerhub.com/api/craig_bayley/PublicAPIDemo/v1

kann es erforderlich sein, oder nicht, wie Sie wählen. Wenn jedoch eine benötigt wird, sollten sie beide sein.

Answer 4

gegenseitig ausschließende Parameter sind möglich (Art) in OpenAPI 3.0:

• Definieren der sich gegenseitig ausschließende Parameter als Objekteigenschaften, und verwenden oneOfmaxProperties oder das Objekt nur 1 Eigenschaft zu begrenzen.
• Verwenden Sie die parameter serialization methodstyle: form und explode: true, so dass das Objekt als ?propName=value serialisiert wird. die minProperties und maxProperties Zwänge

am Beispiel:

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 

Mit 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 

Eine andere Version mit 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] 

Beachten Sie, dass Swagger UI und Swagger Editor die obigen Beispiele noch nicht unterstützen (Stand März 2018). This issue scheint den Parameter Rendering-Teil zu umfassen.

Es gibt auch einen offenen Vorschlag im OpenAPI Spezifikation Repository support interdependencies between query parameters so vielleicht zukünftige Versionen der Spezifikation wird eine bessere Art und Weise muß solche Szenarien zu definieren.