0

我正在尝试使用 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

并且招摇 ui 显示错误如下 -

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

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

4

2 回答 2

1

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

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

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

2-required: 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
于 2016-03-04T05:54:27.683 回答
0

根据规范，如果您设置“in：path”，“required”似乎必须为真。

详细信息可以在这里找到：http ://swagger.io/specification/#parameterObject

于 2016-03-03T08:57:53.857 回答