使用路径参数打开 API POST

Question

我正在尝试使用 Swagger-ui（swagger 版本 2.0）编写一个 Open API 规范，但我不确定如何用 [= 表示 POST 参数15=]参数

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

而swaggerui显示错误如下-

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

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

Answer 1

根据规范，如果设置 "in: path"，"required" 似乎必须为真。

可在此处找到详细信息：http://swagger.io/specification/#parameterObject

Answer 2

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

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

If in is "path", the name field MUST correspond to the associated path segment from the path field in the Paths Object. See Path Templating for further information.

2- required: true 应添加。

If the parameter is in "path", this property is required and its value MUST be 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

使用路径参数打开 API POST

Open API POST with Path Parameter

rest

jsonschema

swagger-ui

swagger-2.0

swagger-editor