如何在Swagger代码生成中处理同一API端点的多方法？

兄弟，我太懂你这个痛点了！之前我在Spring Boot+Angular项目里也碰到过一模一样的情况——同一个POST端点靠请求头区分逻辑，结果Swagger Codegen只挑一个生成，另一个直接丢了。其实问题出在Swagger的默认规则上，咱们只要给两个接口加上唯一的操作标识就能解决。

具体解决方案：给Spring Boot接口添加operationId #

Swagger（不管是Springfox还是SpringDoc）默认会把相同路径+相同HTTP方法的接口视为同一个操作，除非你给它们指定不同的operationId。咱们直接在两个接口上加上@Operation注解来设置唯一ID：

import io.swagger.v3.oas.annotations.Operation;

@PostMapping(value = "/", headers = {"ROLE-ORIGIN=ADMIN"})
@Operation(operationId = "saveAdminUser") // 唯一标识1
public StatusDTO saveUser(@RequestBody AdminDTO dto) {
    // 你的业务逻辑
}

@PostMapping(value = "/", headers = {"ROLE-ORIGIN=PUBLIC"})
@Operation(operationId = "savePublicUser") // 唯一标识2
public StatusDTO saveUser(@RequestBody PublicDTO dto) {
    // 你的业务逻辑
}

生成Angular服务后的效果 #

重新用Swagger Codegen生成Angular服务后，你会得到两个清晰区分的方法，而不是随机的saveUserUsingPOST1/saveUserUsingPOST2：

public saveAdminUser(dto: AdminDTO, observe: any = 'body', reportProgress: boolean = false ): Observable<StatusDTO> {
    // 自动生成的请求逻辑，会带上ROLE-ORIGIN=ADMIN头
}

public savePublicUser(dto: PublicDTO, observe: any = 'body', reportProgress: boolean = false ): Observable<StatusDTO> {
    // 自动生成的请求逻辑，会带上ROLE-ORIGIN=PUBLIC头
}

补充说明 #

• 如果你用的是旧版Springfox（Swagger 2.x），对应的注解是@ApiOperation(value = "xxx", nickname = "saveAdminUser")，nickname就相当于OpenAPI 3.x里的operationId。
• 这种同一端点靠请求头区分业务逻辑的设计完全符合REST最佳实践，你不用怀疑自己的思路，只要让Swagger能识别出这是两个独立操作就行。

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