Swagger UI 未显示具有相同路径但不同 HTTP 方法的操作

Question

例如我有 2 个 API 操作：

获取 v1/people/{id}

发布 v1/people/{id}

我的 Swagger UI API 文档中仅显示了这些操作之一，但我希望同时显示这两个操作。我有很多这样的例子。Swagger 文档中指出：

“ Swagger 将独特的操作定义为路径和 HTTP 方法的组合。 ”

这会让我觉得我想做的事情是可能的，因为它们是由 HTTP 方法唯一标识的。

如果我更改 swagger.yaml 文件中的一个路径参数，它们都会显示。例如：

获取 v1/people/{personid}

发布 v1/people/{id}

但我宁愿保持它们都是标准的，否则我的 API 文档会显得混乱。

我正在使用 swagger-ui-express 4.1.4。

/v1/people/{id}:
get:
  summary: Get people.
  security:
    - cookieAuth: []
  tags:
    - People
  parameters:
    - in: path
      name: id
      required: true
      schema:
        type : integer
        example: 123
  responses: 
    '200':
      description: OK



/v1/people/{id}:
    post:
      summary: Get people.
      security:
        - cookieAuth: []
      tags:
        - People
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type : integer
            example: 123
      responses: 
        '200':
          description: OK

感谢您的帮助。

Answer 1

您可以使用不同的方法尝试相同的路径：https://swagger.io/docs/specification/paths-and-operations/。

paths:
  /users/{id}:
    summary: Represents a user
    description: >
      This resource represents an individual user in the system.
      Each user is identified by a numeric `id`.
    get:
      ...
    patch:
      ...
    delete:
      ...

在你的例子中：

/v1/people/{id}:
  get:
    summary: Get people.
    security:
      - cookieAuth: []
    tags:
      - People
    parameters:
      - in: path
        name: id
        required: true
        schema:
          type : integer
          example: 123
    responses: 
      '200':
        description: OK
  post:
    summary: Get people.
    security:
      - cookieAuth: []
    tags:
      - People
    parameters:
      - in: path
        name: id
        required: true
        schema:
          type : integer
          example: 123
    responses: 
      '200':
        description: OK