不允许在路径中使用Swagger查询字符串

Question

有人能解释我为什么有错误吗？

不允许路径中的查询字符串。

我使用OpenApi 3.0.1，并按照这个文档描述了这部分代码。所以这个错误不应该出现，但它是，为什么？

/posts/{postid}?offset=0&limit=5:
get:
  tags:
  - posts
  summary: example
  description: 'example text'
  operationId: getComments
  parameters:
  - name: postId
    in: path
    description: Post id
    required: true
    schema:
      type: string
  - name: offset
    in: query
    schema:
      type: integer
    description: The number of items to skip before starting to collect the result set
    required: false
  - in: query
    name: limit
    schema:
      type: integer
    description: The numbers of items to return
    required: false
  responses:
    200:
      description: example desc
      content:
        application/json:
          schema:
            items:
              $ref: '#/components/schemas/ResponseData'
    422:
      description: Unprocessable entity
      content: {}

谢谢。

Answer 1

你应该写：

/posts/{postid}

而不是

/posts/{postid}?offset=0&limit=5:

参数部分中偏移量和限制的定义足以知道这些是查询参数，因为它们已经包含属性in: query。

如果您查看https://swagger.io/docs/specification/describing-parameters/，并不是说您应该按照swagger规范的paths部分添加查询字符串。(可能令人困惑的是，会显示一些包含查询字符串的GET请求，这可能会使您感到困惑，认为您应该像swagger规范中那样编写查询字符串。)