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

Question

这个问题已经有答案了:

Swagger API which is having query string (3 个回答)

已关闭 3 年前。

有人可以解释一下为什么我会出错

Query string in path are not allowed

我使用 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 的定义足以知道这些是查询参数，因为它们已经包含属性 in: query。

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