如何在Swagger UI中添加200以外的其他响应码？

默认情况下原生OpenAPI（Swagger）依赖的自动生成逻辑仅会识别接口正常返回的200状态码对应的响应Schema，其余4xx、5xx等非成功响应码的相关配置需要手动添加，原生能力不支持自动生成非200响应的Schema。

常用配置方式 #

下面是Java Spring生态下两种最常用的配置方案：

1. 单个接口单独配置 #

如果不同接口的异常返回结构存在差异，可以直接在对应接口方法上添加注解配置：

• 如果你使用的是SpringDoc OpenAPI（目前主流维护的OpenAPI实现），可以用@ApiResponse注解配置，示例代码如下：

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;

@Operation(summary = "获取用户详情")
@ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "查询成功", 
        content = @Content(schema = @Schema(implementation = UserVO.class))),
    @ApiResponse(responseCode = "400", description = "请求参数错误", 
        content = @Content(schema = @Schema(implementation = CommonErrorVO.class))),
    @ApiResponse(responseCode = "401", description = "身份校验失败", 
        content = @Content(schema = @Schema(implementation = CommonErrorVO.class))),
    @ApiResponse(responseCode = "500", description = "服务内部错误", 
        content = @Content(schema = @Schema(implementation = CommonErrorVO.class)))
})
@GetMapping("/user/{id}")
public CommonResult<UserVO> getUserById(@PathVariable Long id) {
    // 业务逻辑实现
}

• 如果你使用的是已停止维护的旧版SpringFox Swagger2，使用的注解包名为io.swagger.annotations.ApiResponse，用法和上述逻辑基本一致。

2. 全局统一配置 #

如果所有接口的异常返回结构都是统一的，你可以配置全局自定义器批量给所有接口添加通用响应码，不需要逐个接口重复编写注解。以SpringDoc OpenAPI为例，只需要注册一个自定义Bean即可：

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.media.Content;
import io.swagger.v3.oas.models.media.Schema;
import io.swagger.v3.oas.models.responses.ApiResponse;
import io.swagger.v3.oas.models.responses.ApiResponses;
import org.springdoc.core.customizers.GlobalOpenApiCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {
    @Bean
    public GlobalOpenApiCustomizer globalResponseCustomizer() {
        return openApi -> {
            // 遍历所有接口的路径配置
            openApi.getPaths().values().forEach(pathItem -> pathItem.readOperations().forEach(operation -> {
                ApiResponses responses = operation.getResponses();
                // 统一添加400响应
                responses.addApiResponse("400", new ApiResponse()
                        .description("请求参数错误")
                        .content(new Content().addMediaType("application/json",
                                new io.swagger.v3.oas.models.media.MediaType().schema(new Schema<>().$ref("#/components/schemas/CommonErrorVO")))));
                // 同理添加401、403、500等其他通用响应码
            }));
        };
    }
}

补充说明：部分第三方增强框架会提供基于全局异常处理器自动扫描响应码的能力，但是原生的OpenAPI官方依赖不支持该特性，仍然需要手动配置。

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