使用路径参数打开 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

而swagger ui显示错误如下-

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

但如果我将其更改为in: query，错误就会消失。我究竟做错了什么？或者在开放 API 规范中指定路径参数的正确方法是什么？

Answer 1

您需要对文档进行一些更改以符合Open API specification。

1- name 字段应匹配路径段（即text

如果 in 是“路径”，则 name 字段必须对应于路径对象中路径字段的关联路径段。有关详细信息，请参阅路径模板。

2- 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”，则“必需”似乎必须为真。

详情请见：http://swagger.io/specification/#parameterObject