如何在 swagger 中傳遞多值查詢參數

Question

我在 swagger.yml 中有以下服務。 編寫該服務以便可以多次傳遞 page_id。 例如/pages?page_id[]=123&page_id[]=542

我檢查了此鏈接https://swagger.io/specification/，但無法理解如何更新 yml 以便我可以多次傳遞 id。

我看到我必須設置collectionFormat但不知道如何設置。

我嘗試像下面那樣更新它，但沒有運氣https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md 。

它生成的 url 像 ' http://localhost:0000/pages?page_id=123%2C%20542 `

 '/pages':
    get:
      tags:
        - 
      summary: get the list of pages
      operationId: getPages
      produces:
        - application/json
      parameters:
        - name: page_id
          in: query
          description: some description
          required: false
          type: string
          collectionFormat: multi
        - name: page_detail
          in: query
          description: some description
          required: false
          type: string
      responses:
        '200':
          description: OK
        '401':
          description: Authentication Failed
        '404':
          description: Not Found
        '503':
          description: Service Not Available

Answer 1

你快到了。 將參數命名為page_id[] ，使其type: array並使用collectionFormat: multi ：

      parameters:
        - name: page_id[]
          in: query
          description: some description
          required: false
          type: array
          items:
            type: string   # or type: integer or whatever the type is 
          collectionFormat: multi

請注意，請求將以[和]字符百分比編碼為%5B和%5D ，因為它們是根據RFC 3986保留的字符。

http://example.com/pages?page_id%5B%5D=123&page_id%5B%5D=456

Answer 2

來自文檔：

parameters:
- name: id
  in: path
  description: ID of pet to use
  required: true
  schema:
    type: array
    style: simple
    items:
      type: string

您必須將參數定義為數組。

Answer 3

如何為數組類型的查詢參數添加默認值：

    parameters:
      - name: 'liabilityType[]'
        in: query
        description: liabilityType filters the servicers list according to liability types.
        required: false
        schema:
          type: array
          items:
            type: string
        collectionFormat: multi
        value:
          - CAR
          - HOUSE

我附上了這張代碼在 Swagger UI [1] 中的樣子的圖片： https : //i.stack.imgur.com/MSSaJ.png