Swagger-UI 自定义显示返回状态码

最新推荐文章于 2024-02-24 12:32:20 发布

LitongZero

最新推荐文章于 2024-02-24 12:32:20 发布

阅读量1.1w

点赞数 3

CC 4.0 BY-SA版权

分类专栏： # SpringBoot 工具文章标签： Swagger自定义返回状态码 Swagger自定义状态码 spring boot 在线接口文档

本文链接：https://blog.csdn.net/LitongZero/article/details/103822643

工具同时被 2 个专栏收录

41 篇文章

订阅专栏

SpringBoot

21 篇文章

订阅专栏

本文介绍如何在Swagger中自定义接口返回状态码，包括单接口设置及全局配置方法，通过枚举类实现状态码的灵活管理和维护。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

Swagger-UI 自定义显示返回状态码

注: Swagger-bootstrap-ui 方法同样

Swagger，作为一个在线文档，是非常好用的，正确的使用这个，可以使我们少些很多接口文档。

1.问题背景：

做为接口文档，那必然是要有，`全局错误状态码`说明的功能。

而Swagger在参数，相应，都用相应的注解，同样，在状态码也是有相应的注解的。

默认的状态码，只有200，如下：

在这里插入图片描述

2.单接口设置返回状态码

@PostMapping("/login")
    @ApiOperation(value = "登录", notes = "")
    @ApiOperationSupport(order = 1)
    @ApiResponses({
            @ApiResponse(code = 1000, message = "非HTTP状态码，返回值JSON code字段值，描述：成功"),
            @ApiResponse(code = 401, message = "非HTTP状态码，返回值JSON code字段值，描述：无token")
    })
    public R<LoginRes> login(@RequestBody @Validated LoginReq req) {
        ......
        return R.ok(login);
    }

添加后，如下

虽然达到了目的，但是，这样一个一个方法的添加，显然是不够方便的，所以，看下面全局添加状态码。

这种方法可以适用于单个接口添加特定状态码说明。

在这里插入图片描述

3.全局设置状态码

打开`Swagger配置类`，找到初始化`Docket`的地方。添加如下代码

@Bean
    public Docket api(SwaggerProperties swaggerProperties) {
        .....................
        其他配置这里不过多展示
		.....................
        //添加全局响应状态码
        List<ResponseMessage> responseMessageList = new ArrayList<>();
        Arrays.stream(ErrorEnums.values()).forEach(errorEnums -> {
            responseMessageList.add(
                    new ResponseMessageBuilder().code(errorEnums.getCode()).message(errorEnums.getMsg()).responseModel(
                            new ModelRef(errorEnums.getMsg())).build()
            );
        });
        //noinspection Guava
        return new Docket(DocumentationType.SWAGGER_2)
                // 添加全局响应状态码
                .globalResponseMessage(RequestMethod.GET, responseMessageList)
                .globalResponseMessage(RequestMethod.POST, responseMessageList)
                .globalResponseMessage(RequestMethod.PUT, responseMessageList)
                .globalResponseMessage(RequestMethod.DELETE, responseMessageList)
        ......................
        其他配置这里不过多展示
		......................
                .host(swaggerProperties.getHost())
                .apiInfo(apiInfo(swaggerProperties)).select()
                .apis(RequestHandlerSelectors.basePackage(swaggerProperties.getBasePackage()))
                .paths(Predicates.and(Predicates.not(Predicates.or(excludePath)), Predicates.or(basePath)))
                .build()
                .securitySchemes(securitySchemas())
                .securityContexts(Collections.singletonList(securityContext()))
                .pathMapping("/");
    }