路径中不允许使用 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:

参数部分中 offset 和 limit 的定义足以知道这些是查询参数，因为它们已经包含 property in: query。

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