如何在OpenAPI 3.0.0中定义同路径同请求类型但参数不同的端点？

首先明确几个核心点：

1. requestBody.required的正确用法 #

required: false的官方定义就是请求体可选——客户端既可以发送符合schema的请求体，也可以完全不发送请求体，这两种情况都属于合法请求。它不仅限于"请求体可为空"的场景，也覆盖"完全没有请求体"的情况，所以你考虑的这个用法本身是符合规范的。

但这里有个关键问题：你的场景是两个独立的Controller方法处理同一路径的POST请求（一个带请求体，一个不带），而OpenAPI 3.0规范中，同一个路径+HTTP方法只能定义一个operation（操作），没法直接映射两个独立的处理逻辑。

2. 适配场景的OpenAPI定义方式 #

方式一：合并为单个操作，通过描述区分逻辑 #

既然OpenAPI不支持同路径同方法下的多个操作，只能把两种请求场景合并到一个定义里，同时在描述中明确两种情况对应的处理逻辑：

paths:
  /endpoint/path/post:
    post:
      summary: 创建资源（支持两种请求模式）
      description: |
        - 当携带`RandomObject`结构的JSON请求体时，执行Controller1的create逻辑
        - 当不携带任何请求体时，执行Controller2的createDifferent逻辑
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RandomObject'
      responses:
        '200':
          description: 处理成功
          content:
            application/json:
              schema:
                type: object
                # 根据实际返回结构补充字段

这种方式能满足"验证端点与OpenAPI定义一致性"的需求，但缺点是没法在规范层面区分两个独立的处理逻辑，只能靠文字说明。

方式二：调整Spring Boot路由，拆分OpenAPI操作 #

如果允许修改Controller代码，建议给其中一个方法添加匹配条件（比如请求头、请求参数），让两个请求在OpenAPI中可以被明确区分：
比如给无请求体的方法添加特定请求头：

@PostMapping(value = "/endpoint/path/post", headers = "X-Request-Mode=empty-body")
public ResponseEntity<Void> createDifferent() {
    // 业务逻辑
}

对应的OpenAPI就可以定义两个独立的POST操作：

paths:
  /endpoint/path/post:
    post:
      summary: 通过请求体创建资源
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RandomObject'
      responses:
        '200':
          description: 创建成功
    post:
      summary: 无请求体创建资源
      parameters:
        - in: header
          name: X-Request-Mode
          required: true
          schema:
            type: string
            enum: [empty-body]
      responses:
        '200':
          description: 创建成功

这种方式更符合OpenAPI的设计理念，能清晰区分两个独立的端点逻辑。

3. 关于Spring Boot允许同路径同方法的原因 #

Spring MVC的请求匹配机制会根据请求的特征（是否包含匹配的@RequestBody、请求头、参数等）自动选择最匹配的方法。比如：

• 当请求携带application/json类型的请求体时，会优先匹配带@RequestBody RandomObject的方法；
• 当请求没有请求体，或请求体类型不匹配时，会匹配不带@RequestBody的方法。

内容的提问来源于stack exchange，提问作者Miss Skooter