SpringBoot入门到精通（十一）：整合Swagger3.0-定制RESTful与统一接口返回值

愛していますササ

已于 2023-06-15 13:17:43 修改

阅读量498

点赞数

于 2020-11-19 14:47:00 首次发布

愛していますササ原创，盗用揪责

本文链接：https://blog.csdn.net/qq_39866607/article/details/131099516

版权

本文详细介绍了如何在SpringBoot项目中整合Swagger3.0，实现RESTful接口的文档化，并展示了如何定制统一的接口返回值格式，包括定义枚举状态码、响应POJO类以及使用ResponseBodyAdvice处理返回值，进一步讨论了统一异常处理的高级处理方式。

摘要由CSDN通过智能技术生成

整合Swagger3.0-定制RESTful与统一接口返回值

一，整合Swagger3.0

　　随着Spring Boot、Spring Cloud等微服务的流行，在微服务的设计下，小公司微服务工程jar小的几十个，大公司大的工程拆分jar多则几百上万个，这么多的微服务必定产生了大量的接口调用。而接口的调用就必定要写接口文档(由开发人员编写)。

　　存在的问题：(面对多个开发人员或多个开发团队)

项目开发接口众多，细节，复杂，且多样化，高质量地创建接口文档费时，费力。
随着项目的进行，不可避免整改和优化，需要不断的修改接口实现，伴随着也需要同时修改接口文档，管理不方便不说，还容易出现不一致的情况。

概述

　　Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

　　实际开发过程中Swagger 能够完美的与Spring Boot程序整合，组织出强大RESTful API文档，它既可以减少我们创建文档的工作量，同时也整合了说明内容在实现代码中，让维护文档和修改代码融为一体，可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2还提供了强大的页面测试功能，让开发者能快速的调试每个RESTful API。

1.整合实现

1，引入pom依赖。

　　Swagger3.0的更新还是有很大变化的(详情参考)，首先在依赖jar问题上，它新增了springfox-boot-starter，修复了2.x版本的冲突，移除了guava。另外Swagger3.0还移除了注解@EnableSwagger2，增加注解@EnableOpenApi。

 <!-- SpringBoot整合springfox-swagger3 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

　　启动SpringBoot主程序，可以直接测试访问：

　　测试地址：http://localhost:8080/swagger-ui/index.html (访问后提供的有默认的错误调用接口文档)

　　需要注意的是，Swagger3.0还更新了UI页面地址，如上，而Swagger2.x的访问地址是这样的：http://localhost:8080/swagger-ui.html

2，自定义SwaggerConfig类

　　新增SwaggerConfig类，并将其加载到Spring IOC中。需要注意：自定义Swagger配置类，Swagger3.0移除注解@EnableSwagger2，增加注解@EnableOpenApi。@EnableOpenApi可以在Config类中应用，也可以在SpringBoot主启动类上使用(选其一即可)，表示启用自定义API接口。

 1 @EnableOpenApi   // 开启Swagger自定义接口文档
 2 @Configuration   // 相当于Spring配置中的<beans>
 3 public class SwaggerConfig {
 4     @Bean   // 相当于Spring 配置中的<bean>
 5     public Docket createRestApi() {
 6         return new Docket(DocumentationType.OAS_30)
 7                 .apiInfo(apiInfo())
 8                 .select()
 9                 .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
10                 .paths(PathSelectors.any())
11                 .build();
12     }
13     // API基础信息定义(就是更新Swagger默认页面上的信息)
14     private ApiInfo apiInfo() {
15         return new ApiInfoBuilder()
16                 .title("Swagger3接口文档测试")
17                 .description("文档描述：更多问题，请联系开发者")
18                 .contact(new Contact("xsge123(name)", "作者网站(url)", "1511868921@qq.com(email)"))
19                 .version("1.0")
20                 .build();
21     }
22     
23 }

3，编写Controller提供RESTful风格的接口API

编写Controller前，先看看一些注解的意思吧！

@Api：用在控制器类上，表示对类的说明
    tags="说明该类的作用，可以在UI界面上看到的说明信息的一个好用注解"
    value="该参数没什么意义，在UI界面上也看到，所以不需要配置"

@ApiOperation：用在请求的方法上，说明方法的用途、作用
    value="说明方法的用途、作用"
    notes="方法的备注说明"

@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面(标注一个指定的参数，详细概括参数的各个方面，例如：参数名是什么？参数意义，是否必填等)
        name：属性值为方法参数名
        value：参数意义的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path(用于restful接口)--> 请求参数的获取：@PathVariable
            · div(不常用)
            · form(不常用)    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值

@ApiResponses：用在请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：状态码数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类

@ApiModel：用于响应类上(POJO实体类)，描述一个返回响应数据的信息(描述POJO类请求或响应的实体说明)
            (这种一般用在post接口的时候，使用@RequestBody接收JSON格式的数据的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候)