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

Question

例如我有 2 个 API 操作：

获取v1/people/{id}

POST v1/people/{id}

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

"Swagger 将唯一操作定义为路径和 HTTP 方法的组合。"

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

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

获取v1/people/{personid}

POST 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

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

Swagger UI not showing operations with same Path but different HTTP method

node.js

swagger

swagger-ui