如何在Swagger（OpenAPI）中定義互斥查詢參數？

我有揚鞭一系列參數，這樣必須填寫如何在Swagger（OpenAPI）中定義互斥查詢參數？

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

的一個參數，但它並不重要哪一個，其他人可以留空。有沒有辦法在Swagger中表示這個？

來源

2014-01-15 lorless

不錯的問題我不認爲這是，如果你找到出路請分享:) –

我面臨同樣的問題。你有解決它嗎？ – eskalera

不幸的是，它看起來像這個功能不可用 – lorless

不幸的是，目前在Swagger中這是不可能的。「required」只是一個布爾值，並且無法表示參數之間的相互依賴關係。

您可以做的最好的事情就是明確參數描述中的要求，並在同一行中放入自定義的400錯誤請求描述。

（有在https://github.com/swagger-api/swagger-spec/issues/256關於揚鞭的下一個版本實現這種可能的方式有點討論）

來源

2015-05-22 13:41:27

有關更改API的設計是什麼？目前你有一個方法，3個參數。如果我理解的很好，用戶必須始終提供一個參數，剩下的兩個必須未設置。

對我來說，API會更可用具有三個端點樣

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

來源

2015-05-30 21:48:49

解決技術問題，但不是很安靜。 –

一個替代方案是在過濾器中類型的參數來傳遞與一個枚舉，並且與值的濾波值來使用。

例在：https://app.swaggerhub.com/api/craig_bayley/PublicAPIDemo/v1

可以要求或不，任您選擇。但是，如果需要，他們都應該。

來源

2016-11-23 23:13:54

我的理解是否正確，在這種情況下，您的提案將產生API /用戶？name = name＆filterType = [name | site | survey]？我同意，因爲這是更重要的，因爲我們有單一資源，因爲它應該是（仍然有乾淨和可用的API）。 –

互斥參數在OpenAPI 3.0是可能的（排序的）：

定義互斥參數爲對象屬性和使用oneOf或maxProperties到對象限制爲只有1屬性。
使用parameter serialization methodstyle: form和explode: true，以便將對象序列化爲?propName=value。

使用minProperties和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

使用oneOf：使用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

另一個版本：

 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]

請注意，Swagger UI和Swagger編輯器不支持以上示例（截至2018年3月）。 This issue似乎覆蓋了參數渲染部分。

在OpenAPI規範存儲庫中還有一個開放的提議，要求support interdependencies between query parameters，因此規範的未來版本可能會有更好的方式來定義這樣的場景。

來源

2018-03-09 17:38:37 Helen

如何在Swagger（OpenAPI）中定義互斥查詢參數？

回答

相關問題