springboot 集成 Swagger2（速通）

水深无声 2023-10-10 21:17 27阅读 0赞

#### 目录 ####

*  1. 概述
 *  2. 案例 1
 *  3. UI 的简单使用
 *  4. 简单配置 Docket 对象
 *   *  1. 配置文档的描述信息
     *  2. 定义包扫描规则
 *  5. 指定接口不生成文档
 *   *  1. 自定义注解
     *  2. 路径匹配
 *  6. 常用注解

## 1. 概述 ##

简单理解——代写接口文档的框架，可跟随接口修改实时更新。

Open API 格式：REST API 的描述格式，可使用 YAML 或 JSON 格式来编写。Open API 的描述范围：

*  每个访问地址的类型；
 *  每个操作的参数；
 *  认证方法；
 *  连接信息、声明，使用团队和其他信息。

Swagger ：一套围绕 Open API 规范构建的一款 RESTful 接口的文档在线自动生成和功能测试 API。将相关信息通过 YAML/JSON 格式存储在描述文件中，再通过描述文件去更新接口文档。其工具组包：

*  Swagger Editor：基于浏览器编辑器，可以编写 Open API 规范；
 *  **Swagger UI**：将 Open API 规范呈现为交互式 API 文档，即描述文件（常用）；
 *  Swagger Codegen：将描述文件生成 HTML 和 cwiki 形式的接口文档，可同时生成多种语言的客户端和服务端代码；
 *  Swagger Inspector：类似 Swagger UI，但包含更多信息，比如请求的实际参数数据；
 *  Swagger Hub：集成上面工具的所有功能，上传描述文件到 Hub ，就可以完成上面工具的所有工作。

Springfox：Swagger 在遇到版本迭代的时候还需要更改描述文件，但 Springfox 则优化了此过程，会根据代码实时生成文档。通过注解的方式将 Swagger 集成在代码中。

## 2. 案例 1 ##

依赖：

*  web 项目
    
        <dependency>
                    <groupId>org.springframework.boot</groupId>
                    <artifactId>spring-boot-starter-web</artifactId>
                </dependency>
 *  springfox 依赖，要一次性导入下面两个，版本要对应
    
        <dependency>
                    <groupId>io.springfox</groupId>
                    <artifactId>springfox-swagger2</artifactId>
                    <version>2.9.2<</version>
                </dependency>
                <dependency>
                    <groupId>io.springfox</groupId>
                    <artifactId>springfox-swagger-ui</artifactId>
                    <version>2.9.2<</version>
                </dependency>

注解：

*  启动类注解：
    
        @EnableSwagger2         // 开启 swagger2 相关技术，扫描当前类所在包及其子包中的注解 
        @SpringBootApplication
 *  控制类：
    
        @RestController
        public class SwaggerController {
              
            @GetMapping("/get")
            public String getStr(String str) {
              
                return "SELECT " + str;
            }
        
            @PostMapping("/post")
            public String postStr(String str) {
              
                return "CREATE " + str;
            }
        
            @PutMapping("/put")
            public String putStr(String str) {
              
                return "UPDATE " + str;
            }
        
            @PatchMapping("/patch")
            public String patchStr(String str) {
              
                return "UPDATE " + str;
            }
            
            @DeleteMapping("/delete")
            public String deleteStr(String str) {
              
                return "DELETE " + str;
            }
        }
 *  运行代码，访问 *http://127.0.0.1:8080/swagger-ui.html*，这里可能会遇到以下的报错：
    
    > 启动项目遇到报错：**java: 警告: 源发行版 17 需要目标发行版 17**  
    > 解决方案：[https://blog.csdn.net/weixin\_44299027/article/details/120848738][https_blog.csdn.net_weixin_44299027_article_details_120848738]  
    >   
    >   
    > 启动项目遇到报错：**类文件具有错误的版本 61.0, 应为 52.0**  
    > 解决方案：spring6.0 开始 jdk 要求17以上才行，要么升级 JDK，要么降低 spring 版本。  
    > 我选择降低 spring 版本：
    > 
    >  *  [https://mvnrepository.com/][https_mvnrepository.com] 查看 spring-boot-starter-parent 的版本号
    >  *  选择 3 以下的版本号，修改 Maven 依赖 spring-boot-starter-parent
    > 
    >   
    > 启动项目遇到报错：**Failed to start bean ‘documentationPluginsBootstrapper’;**  
    > 解决方案：springboot 升级到 2.6.0之后，swagger版本和springboot出现了不兼容情况，要么降低 springboot 版本，要么配置 `spring.mvc.pathmatch.matching-strategy=ant_path_matcher`
    > 
    >  *  A.降低 springboot 版本不再做赘述（可降低至 2.5 以下就绝对没问题）；
    >  *  B.配置1：① 启动类加上注解 `@EnableWebMvc`；② 配置文件加上 `spring.mvc.pathmatch.matching-strategy=ant_path_matcher`;
    >  *  C.配置1不生效情况：参考：[https://blog.csdn.net/weixin\_39792935/article/details/122215625][https_blog.csdn.net_weixin_39792935_article_details_122215625]
    >  *  D.当上述三种解决方案都不生效的情况下，我采用的终极**解决方案：降低 Springboot 版本（2.5.6），并采用 C 方案的配置**，然后访问 [http://127.0.0.1:8080/swagger-ui.html][http_127.0.0.1_8080_swagger-ui.html]  
    >       
    >     访问页面为空：  
    >     ![75626081467c402f93df001abf0ec679.png][]  
    >     解决方案：启动类加上注解`@EnableOpenApi`，并访问 *http://localhost:8080/swagger-ui/index.html*
 *  解决无法访问的问题：
    
     *  修改配置文件 application.properties
        
            spring.mvc.pathmatch.matching-strategy=ant_path_matcher
     *  新增配置类：
        
            package com.chenjy.swagger.config;
            
            import org.springframework.context.annotation.Configuration;
            import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
            import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
            
            /**
             * @Desc 解决高版本无法兼容 swagger2 的问题
             *       如此配置之后，就可通过 http://127.0.0.1:8080/doc.html 去访问 swagger-ui.html
             */
            @Configuration
            public class WebMvcConfigurer extends WebMvcConfigurationSupport {
                    
            
                /**
                 * 发现如果继承了WebMvcConfigurationSupport，则在yml中配置的相关内容会失效。 需要重新指定静态资源
                 */
                @Override
                public void addResourceHandlers(ResourceHandlerRegistry registry) {
                    
                    registry.addResourceHandler("/**").addResourceLocations(
                            "classpath:/static/");
                    registry.addResourceHandler("swagger-ui.html", "doc.html").addResourceLocations(
                            "classpath:/META-INF/resources/");
                    registry.addResourceHandler("/webjars/**").addResourceLocations(
                            "classpath:/META-INF/resources/webjars/");
                    super.addResourceHandlers(registry);
                }
            
            }
     *  降低 springboot 版本到 2.5.6
        
            <parent>
                    <groupId>org.springframework.boot</groupId>
                    <artifactId>spring-boot-starter-parent</artifactId>
                    <version>2.5.6</version>
                    <relativePath/> 
                </parent>
 *  访问界面如下图，可以从中看到我们写的接口：  
    ![5092e5b47b804cf7b54bfacd28ceff85.png][]

## 3. UI 的简单使用 ##

扫描项目中（启动类同级目录及其子目录中）的所有控制器（默认是控制器） 中的 `@GetMapping/@RequestMapping(method = {RequestMethod.GET})` 系列的注解，然后去解析注解对应的映射地址以及注解约束的请求方式（GET、POST、DELET…，默认为 GET）。点击具体方法可看详细的请求信息：  
![d777de0d41294251ae00a8ecaf3d3b55.png][]  
可点击 Try it out 测试一下：  
![e6bc668542df429d9125136651475751.png][]

## 4. 简单配置 Docket 对象 ##

### 1. 配置文档的描述信息 ###

package com.chenjy.swagger.config;
    
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.service.Contact;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    
    @Configuration
    public class SwaggerConfigurer {
        
    
        /**
         * @return Docket——Swagger 中的全局配置对象
         */
        @Bean
        public Docket docket() {
        
            // DocumentationType.SWAGGER_2 告诉 Springfox 当前的 Swagger 版本是 Swagger2
            Docket docket = new Docket(DocumentationType.SWAGGER_2);
            // API 帮助文档的描述信息
            ApiInfo apiInfo = new ApiInfoBuilder()
                    .title("Swagger 文档")// 文档标题
                    .description("Swagger ：一套围绕 Open API 规范构建的一款 RESTful 接口的文档在线自动生成和功能测试 API。")// 描述信息
                    .version("1.0.1")// 版本号
                    .contact(
                            // name url email
                            new Contact("364.99°的文档", // 文档发布者名称
                                    "https://blog.csdn.net/m0_54355172", // 文档发布者的网站地址
                                    "2190826197@qq.com" // 文档发布者的邮箱
                            )
                    )
                    // 构建器模式
                    .build();
            // 给 docket 上下文配置 API 描述信息
            docket.apiInfo(apiInfo);
            return docket;
        }
    }

![6f79733e467c46e5bdbccdfa24c107c2.png][]

### 2. 定义包扫描规则 ###

在 docket 方法中添加以下配置：

docket
                    .select() // 获取 docket 中的选择器，如：扫描哪个包的注解
                    .apis(RequestHandlerSelectors.basePackage("com.chenjy.swagger.controller")); // 定义规则——包扫描规则

![114f9d110980405aaae96c2e2474462c.png][]

## 5. 指定接口不生成文档 ##

### 1. 自定义注解 ###

[→ ***如何自定义一个注解*** ←][Link 1]

定义一个注解，标注当前接口不需要生成 Swagger 文档：

package com.chenjy.swagger.annotation;
    
    import java.lang.annotation.ElementType;
    import java.lang.annotation.Retention;
    import java.lang.annotation.RetentionPolicy;
    import java.lang.annotation.Target;
    
    @Target({
        ElementType.METHOD, ElementType.TYPE}) // 此注解用于描述 方法、类
    @Retention(RetentionPolicy.RUNTIME)// 注释信息会在运行时被有效
    public @interface NoSwagger {
        
        // 自定义注解属性 @NoSwagger(value="")
        String value() default "";
    }

配置类使注解规则生效：

package com.chenjy.swagger.config;
    
    import com.chenjy.swagger.annotation.NoSwagger;
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.service.Contact;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    
    import static com.google.common.base.Predicates.not;
    import static springfox.documentation.builders.RequestHandlerSelectors.withMethodAnnotation;
    
    @Configuration
    public class SwaggerConfigurer {
        
    
        /**
         * @return Docket——Swagger 中的全局配置对象
         */
        @Bean
        public Docket docket() {
        
            // DocumentationType.SWAGGER_2 告诉 Springfox 当前的 Swagger 版本是 Swagger2
            Docket docket = new Docket(DocumentationType.SWAGGER_2);
            // API 帮助文档的描述信息
            ApiInfo apiInfo = new ApiInfoBuilder()
                    .title("Swagger 文档")// 文档标题
                    .description("Swagger ：一套围绕 Open API 规范构建的一款 RESTful 接口的文档在线自动生成和功能测试 API。")// 描述信息
                    .version("1.0.1")// 版本号
                    .contact(
                            // name url email
                            new Contact("364.99°的文档", // 文档发布者名称
                                    "https://blog.csdn.net/m0_54355172", // 文档发布者的网站地址
                                    "2190826197@qq.com" // 文档发布者的邮箱
                            )
                    )
                    // 构建器模式
                    .build();
            // 给 docket 上下文配置 API 描述信息
            docket.apiInfo(apiInfo);
            Docket build = docket
                    .select() // 获取 docket 中的选择器，如：扫描哪个包的注解
                    .apis(
                            not( // 取反
                                    withMethodAnnotation(NoSwagger.class) // 当方法上有注解的时候返回 true
                            )
                    )
                    .apis(RequestHandlerSelectors.basePackage("com.chenjy.swagger.controller")) // 定义规则——包扫描规则
                    .build();
            return build;
        }
    }

**注意：** 这里需要重新 build 一次 Docket ，然后返回重新 build 之后的 docket，否则不会生效。

标注在接口方法上：

@NoSwagger
        @PatchMapping("/patch")
        public String patchStr(String str) {
        
            return "UPDATE " + str;
        }

重启项目，访问：  
![77278759341a4540942700fd5746d14e.png][]

优化写法：

Docket build = docket
                    .select() // 获取 docket 中的选择器，如：扫描哪个包的注解
                    .apis(
                            and(
                                    not( // 取反
                                            withMethodAnnotation(NoSwagger.class) // 当方法上有注解的时候返回 true
                                    ),
                                    RequestHandlerSelectors.basePackage("com.chenjy.swagger.controller")
                            )
                    )
                    .build();
            return build;

**注意：**

*  `and` 和 `not` 都是 *com.google.common.base.Predicates* 中的静态方法；
 *  `withMethodAnnotation` 是 *springfox.documentation.builders.RequestHandlerSelectors* 中的静态方法。

### 2. 路径匹配 ###

*springfox.documentation.builders.PathSelectors*

只有路径前缀为 /test 的接口方法才会生成文档。

Docket build = docket
                    .select() // 获取 docket 中的选择器，如：扫描哪个包的注解
                    .paths(
                            PathSelectors.regex("/test/.*") // 使用正则表达式  . 任意字符   * 0个或多个
                    )
                    .build();
            return build;

同时多种路径匹配规则：`Predicates.or`

.paths(
                            Predicates.or(
                                    PathSelectors.regex("/test/.*"),
                                    PathSelectors.regex("/.*")
                            )
                    )

[→ 正则表达式语法 ←][Link 2]

## 6. 常用注解 ##

**`@Api(tags = {"test 接口 API"})`**

*  类注解，描述当前类型生成帮助文档的信息；
 *  `tags` 定义控制器别名，可以有多个值，有几个别名，文档中就有几个控制器目录。  
    ![b7d5ac849ecb4c8fa52ac3eccc83cef0.png][]

**`@ApiOperation(value = "get 方法，执行查询操作", notes = "一个小 demo")`**

*  类、方法注解，常用来描述方法。  
    ![cedaad2c0f4d4b3e89fed402adede85d.png][]

**`@ApiParam()`**

*  参数、方法、属性注解，常用来描述参数；
    
        @PostMapping("/post")
        public String postStr(
                @ApiParam(name = "字符串", value = "用来输出的字符串", required = true) String str,
                @ApiParam(name = "序列号", required = false) @RequestParam(defaultValue = "001", required = false)String num
        ) {
              
            return "CREATE " + str + num;
        }
    
    ![92a39efd1b6b401fb8014ddf275848dd.png][]

**`@ApiIgnore`**

*  方法、属性注解，让此注解描述的方法或类型不生成 API 文档。
    
        @ApiIgnore
            @PutMapping("/put")
            public String putStr(String str) {
              
                return "UPDATE " + str;
            }

**`@ApiImplicitParam`**

*  在方法上描述方法参数，只能描述一个参数。
    
        @ApiImplicitParam(
                    name = "str", value = "一个字符串", required = true, paramType = "java.lang.String", dataType = "任意字符串"
            )
            @DeleteMapping("/delete")
            public String deleteStr(String str, Integer num) {
              
                return "DELETE " + str;
            }

**`ApiImplicitParams`**

*  在方法上描述参数，可以描述多个参数。
    
        @ApiImplicitParams(value = {
              
                   @ApiImplicitParam( name = "str", value = "一个字符串", required = true, paramType = "java.lang.String", dataType = "任意字符串" ),
                   @ApiImplicitParam( name = "num", value = "一个整数") 
            })
            @DeleteMapping("/delete")
            public String deleteStr(String str, Integer num) {
              
                return "DELETE " + str;
            }

**`@ApiModel`**

*  描述实体类，当此实体类被作为返回类型用于 API 帮助文档中的接口方法中，此注解被解析。
    
        @Data
        @NoArgsConstructor
        @AllArgsConstructor
        @ApiModel( value = "一个实体类", description = "存储数据并返回")
        public class TestDto {
              
            private String name;
            private Integer num;
        }
    
        @PatchMapping("/patch")
            public TestDto patchStr(String str, Integer num) {
              
                return new TestDto(str, num);
            }

**`@ApiModelProperty`**

*  描述实体类的属性，要搭配 `@ApiModel` 使用。
    
        @Data
        @NoArgsConstructor
        @AllArgsConstructor
        @ApiModel( value = "一个实体类", description = "存储数据并返回")
        public class TestDto {
              
            @ApiModelProperty( value = "姓名", example = "张三", hidden = false)
            private String name;
            @ApiModelProperty( value = "序列号")
            private Integer num;
        }
    
    ![6d7bd63a5ff244fbb380b7c73697a6f3.png][]  
    ![f9e113e719d14f2eb18e6000705861f7.png][]

**注意：**

*  GET：不能使用 `@requestBody` ；
 *  POST：可以使用 `@requestBody` (对于参数转化的配置必须统一)和 `@requestParam` 。

[https_blog.csdn.net_weixin_44299027_article_details_120848738]: https://blog.csdn.net/weixin_44299027/article/details/120848738
[https_mvnrepository.com]: https://mvnrepository.com/
[https_blog.csdn.net_weixin_39792935_article_details_122215625]: https://blog.csdn.net/weixin_39792935/article/details/122215625
[http_127.0.0.1_8080_swagger-ui.html]: http://127.0.0.1:8080/swagger-ui.html#/
[75626081467c402f93df001abf0ec679.png]: https://img-blog.csdnimg.cn/75626081467c402f93df001abf0ec679.png
[5092e5b47b804cf7b54bfacd28ceff85.png]: https://img-blog.csdnimg.cn/5092e5b47b804cf7b54bfacd28ceff85.png
[d777de0d41294251ae00a8ecaf3d3b55.png]: https://img-blog.csdnimg.cn/d777de0d41294251ae00a8ecaf3d3b55.png
[e6bc668542df429d9125136651475751.png]: https://img-blog.csdnimg.cn/e6bc668542df429d9125136651475751.png
[6f79733e467c46e5bdbccdfa24c107c2.png]: https://img-blog.csdnimg.cn/6f79733e467c46e5bdbccdfa24c107c2.png
[114f9d110980405aaae96c2e2474462c.png]: https://img-blog.csdnimg.cn/114f9d110980405aaae96c2e2474462c.png
[Link 1]: https://blog.csdn.net/m0_54355172/article/details/123604827
[77278759341a4540942700fd5746d14e.png]: https://img-blog.csdnimg.cn/77278759341a4540942700fd5746d14e.png
[Link 2]: https://www.runoob.com/regexp/regexp-syntax.html
[b7d5ac849ecb4c8fa52ac3eccc83cef0.png]: https://img-blog.csdnimg.cn/b7d5ac849ecb4c8fa52ac3eccc83cef0.png
[cedaad2c0f4d4b3e89fed402adede85d.png]: https://img-blog.csdnimg.cn/cedaad2c0f4d4b3e89fed402adede85d.png
[92a39efd1b6b401fb8014ddf275848dd.png]: https://img-blog.csdnimg.cn/92a39efd1b6b401fb8014ddf275848dd.png
[6d7bd63a5ff244fbb380b7c73697a6f3.png]: https://img-blog.csdnimg.cn/6d7bd63a5ff244fbb380b7c73697a6f3.png
[f9e113e719d14f2eb18e6000705861f7.png]: https://img-blog.csdnimg.cn/f9e113e719d14f2eb18e6000705861f7.png