Question

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

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是“path”， name 字段必须对应于Paths对象中路径字段的关联路径段。有关详细信息，请参阅路径模板。

应添加required: true。

如果参数在“path”中，则此属性是必需的，其值必须为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

根据规范，似乎＆＃34;要求＆＃34;如果你设置＆＃34; in：path＆＃34;。

，则必须为真

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

使用路径参数

2 个答案: