使用路徑參數打開API POST

Question

我正在嘗試使用Swagger-ui（swagger版本2.0）編寫Open API規范，但不確定如何用path參數表示POST參數。

POST /ping/{text}

我的規格如下

# this is an example of the Uber API
# as a demonstration of an API spec in YAML
swagger: '2.0'
info:
  title: Mock API
  description: Mock API 
  version: "1.0.0"
# the domain of the service
host: api.mock.com
# array of all schemes that your API supports
schemes:
  - https
# will be prefixed to all paths
basePath: /v1
produces:
  - application/json
paths:
  /ping:
    get:
      summary: Ping
      description: |
        Respond to PING requests, similar to heart beat
      parameters:
        - name: path  
          in: path
          description: String input for echo service
          required: false
          type: string
      tags:
        - ping
      responses:
        200:
          description: The text passed in the request
          schema:
            type: string
        default:
          description: Empty response for request passed
          schema:
            type: string

招搖的用戶界面顯示錯誤如下：

 code:  "ONE_OF_MISSING"
 message:  "Not a valid parameter definition"

但是如果我將其更改為in: query錯誤就消失了。 我究竟做錯了什么？ 還是在開放API規范中指定路徑參數的正確方法是什么？

Answer 1

您需要對文檔進行一些更改以符合Open API規范 。

1- name字段應與路徑段匹配（即text

如果in是“ path”，則名稱字段必須對應於Paths對象中來自path字段的關聯路徑段。 有關更多信息，請參見路徑模板。

2- required: true應添加required: true 。

如果參數在“路徑”中，則此屬性是必需的，其值必須為true。

3-如果要記錄POST /ping/{text} ，則需要將get更改為post 。 另外，路徑段（即/{text ）也應添加到路徑中。

這是上述更改之后的最終Swagger文檔：

# this is an example of the Uber API
# as a demonstration of an API spec in YAML
swagger: '2.0'
info:
  title: Mock API
  description: Mock API 
  version: "1.0.0"
# the domain of the service
host: api.mock.com
# array of all schemes that your API supports
schemes:
  - https
# will be prefixed to all paths
basePath: /v1
produces:
  - application/json
paths:
  /ping/{text}:
    post:
      summary: Ping
      description: |
        Respond to PING requests, similar to heart beat
      parameters:
        - name: text  
          in: path
          description: String input for echo service
          required: true
          type: string
      tags:
        - ping
      responses:
        200:
          description: The text passed in the request
          schema:
            type: string
        default:
          description: Empty response for request passed
          schema:
            type: string

Answer 2

根據規范，如果您設置“ in：path”，則似乎“ required”必須為真。

可以在這里找到詳細信息： http : //swagger.io/specification/#parameterObject