SpringBoot实战：整合Swagger3实现在线Api文档

￡神魔★判官ぃ 2023-09-23 18:18 118阅读 0赞

> Swagger-UI 是 HTML、Javascript、CSS 的一个集合，可以动态地根据注解生成在线 Api 文档；swagger-bootstrap-UI 则可以美化 swagger-ui，页面更清爽！本篇就是实现 SpringBoot 整合 Swagger3 实现在线 Api 文档。
> 
> 项目源码实现前分支地址：[https://toscode.gitee.com/li\_ziheng/lizhengi-samples/tree/feature%2Fspring-boot-1.0.1/][https_toscode.gitee.com_li_ziheng_lizhengi-samples_tree_feature_2Fspring-boot-1.0.1]
> 
> 项目源码实现后分支地址：[https://toscode.gitee.com/li\_ziheng/lizhengi-samples/tree/feature%2Fspring-boot-1.0.2/][https_toscode.gitee.com_li_ziheng_lizhengi-samples_tree_feature_2Fspring-boot-1.0.2]
> 
> ～
> 
> 本篇内容包括：项目介绍与条件准备、项目搭建与构造、效果验证

--------------------

### 文章目录 ###

*   *  一、项目介绍与条件准备
     *   *   *  1、项目使用框架/模块介绍
             *  2、Swagger-UI 常用注解
             *  3、项目结构说明
     *  二、项目搭建与构造
     *   *   *  1、添加项目 maven 依赖
             *  2、启动类添加注解
             *  3、添加 Swagger-UI 的配置类
             *  4、WebMvcConfig 防止 Whitelabel Error Page 问题
             *  5、controller 控制层添加 Swagger 注解
             *  6、实体对象 VO 实现
             *  7、controller 控制层实现
             *  8、控制台输出 Swagger 接口文档地址
     *  三、效果验证
     *   *   *  1、控制台输出
             *  2、Swagger-UI
     *  更、维护日志
     *   *   *  12月12日内容更新

--------------------

## 一、项目介绍与条件准备 ##

#### 1、项目使用框架/模块介绍 ####

*  Swagger3：Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务；在 SpringBoot 应用中集成 Swagger3 比老的 Swagger2 简单多了，它提供了一个 Starter 组件；
 *  knife4j：Knife4j 的前身是 swagger-bootstrap-ui，前身 swagger-bootstrap-ui 是一个纯 swagger-ui 的 ui 皮肤项目，可以美化 swagger-ui！

#### 2、Swagger-UI 常用注解 ####

*  `@Api` 注解：用于修饰 Controller 类，生成 Controller 相关文档信息；
 *  `@ApiOperation` 注解：用于修饰 Controller 类中的方法，生成接口方法相关文档信息；
 *  `@ApiParam` 注解：用于修饰接口中的参数，生成接口参数相关文档信息；
 *  `@ApiModelProperty` 注解：用于修饰实体类的属性，当实体类是请求参数或返回结果时，直接生成相关文档信息。

#### 3、项目结构说明 ####

├── config — 配置文件POJO

├── controller — 控制层（将请求通过 url 匹配，分配到不同的接收器/方法进行处理，然后返回结果）

├── service — 服务层接口

└── impl — 服务层实现

├── mapper — 数据访问层，与数据库交互为 service 提供接口

├── entity — 实体对象

├── converter — 实体对象转换器

├── dto — 持久层需要的实体对象（用于服务层与持久层之间的数据传输对象）

└── vo — 视图层需要的实体对象（用于服务层与视图层之间的数据传输对象）

├── utils — 工具类

└── Application.java — 入口启动类

--------------------

## 二、项目搭建与构造 ##

#### 1、添加项目 maven 依赖 ####

\# 添加项目 maven 依赖，*pom.xml* 文件添加内容如下：

<dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-boot-starter</artifactId>
                <version>3.0.0</version>
            </dependency>
            
            <dependency>
                <groupId>com.github.xiaoymin</groupId>
                <artifactId>knife4j-spring-boot-starter</artifactId>
                
                <version>3.0.3</version>
            </dependency>

#### 2、启动类添加注解 ####

\# 启动类添加 `@EnableWebMvc` 注解

package com.lizhengi;
    
    import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    import org.springframework.web.servlet.config.annotation.EnableWebMvc;
    
    /**
     * @author lizhengi
     */
    @SpringBootApplication
    @EnableWebMvc
    public class LizhengiSampleSpringBootApplication {
        
    
        public static void main(String[] args) {
        
            SpringApplication.run(LizhengiSampleSpringBootApplication.class, args);
        }
    
    }

#### 3、添加 Swagger-UI 的配置类 ####

\# Swagger2 API 文档的配置

package com.lizhengi.config;
    
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    /**
     * @author liziheng
     * @version 1.0.0
     * @description Swagger2 API 文档的配置
     * @date 2022-12-09 12:12 上午
     **/
    @Configuration
    @EnableSwagger2
    public class Swagger2Config {
        
    
        @Bean
        public Docket createRestApi() {
        
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    //为当前包下controller生成API文档
                    .apis(RequestHandlerSelectors.basePackage("com.lizhengi.controller"))
                    //为有@Api注解的Controller生成API文档
    //                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                    //为有@ApiOperation注解的方法生成API文档
    //                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        private ApiInfo apiInfo() {
        
            return new ApiInfoBuilder()
                    .title("SwaggerUI演示")
                    .description("SwaggerUI演示")
                    .contact("lizhengi")
                    .version("1.0")
                    .build();
        }
    }

#### 4、WebMvcConfig 防止 Whitelabel Error Page 问题 ####

package com.lizhengi.config;
    
    import org.springframework.context.annotation.Configuration;
    import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
    import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
    
    /**
     * @author liziheng
     * @version 1.0.0
     * @description
     * @date 2022-12-12 3:36 下午
     **/
    @Configuration
    public class WebMvcConfig extends WebMvcConfigurationSupport   {
        
    
        @Override
        public void addResourceHandlers(ResourceHandlerRegistry registry) {
        
            // 下面定义了拦截器，会导致 spring.resources.static-locations 配置失效
            registry.addResourceHandler("/**").addResourceLocations("classpath:/webapp/public/");
    
            // 配置 knife4j 文档资源的访问路径
            registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
            registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        }
    }

#### 5、controller 控制层添加 Swagger 注解 ####

\# Swagger3Config Swagger3 API 文档的配置

package com.lizhengi.config;
    
    import org.springframework.beans.BeansException;
    import org.springframework.beans.factory.config.BeanPostProcessor;
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import org.springframework.util.ReflectionUtils;
    import org.springframework.web.servlet.mvc.method.RequestMappingInfoHandlerMapping;
    
    import springfox.documentation.builders.PathSelectors;
    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 springfox.documentation.spring.web.plugins.WebFluxRequestHandlerProvider;
    import springfox.documentation.spring.web.plugins.WebMvcRequestHandlerProvider;
    
    import java.lang.reflect.Field;
    import java.util.Collections;
    import java.util.List;
    import java.util.stream.Collectors;
    
    /**
     * @author liziheng
     * @version 1.0.0
     * @description Swagger3 API 文档的配置
     * @date 2022-12-09 03:12 上午
     **/
    @Configuration
    public class Swagger3Config {
        
    
        /**
         * API 文档信息
         *
         * @return -
         */
        @Bean
        public Docket api() {
        
            // 自动生成文档接口：http://localhost:8080/v3/api-docs
            // API接口文档界面：http://localhost:8080/swagger-ui/index.html
            // Swagger UI 界面：http://localhost:8080/doc.html
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.liziheng.demo.controller"))
                    .paths(PathSelectors.regex("/article/*.*|/api/v1/*.*|/*.*"))
                    .build();
        }
    
        private ApiInfo apiInfo() {
        
            return new ApiInfo(
                    "Swagger API 文档",
                    "后台管理系统相关的接口",
                    "v1",
                    "协议地址",
                    new Contact("li", "https://github.com/", "@163.com"),
                    "MIT License", "http://opensource.org/licenses/MIT",
                    Collections.emptyList());
        }
    
        /**
         * 解决swagger在springboot2.7以后的空指针异常
         *
         * @return -
         */
        @Bean
        public static BeanPostProcessor springfoxHandlerProviderBeanPostProcessor() {
        
    
            return new BeanPostProcessor() {
        
                @Override
                public Object postProcessAfterInitialization(Object bean, String beanName) throws BeansException {
        
                    if (bean instanceof WebMvcRequestHandlerProvider || bean instanceof WebFluxRequestHandlerProvider) {
        
                        customizeSpringfoxHandlerMappings(getHandlerMappings(bean));
                    }
                    return bean;
                }
    
                private <T extends RequestMappingInfoHandlerMapping> void customizeSpringfoxHandlerMappings(List<T> mappings) {
        
                    List<T> copy = mappings.stream()
                            .filter(mapping -> mapping.getPatternParser() == null)
                            .collect(Collectors.toList());
                    mappings.clear();
                    mappings.addAll(copy);
                }
    
                @SuppressWarnings("unchecked")
                private List<RequestMappingInfoHandlerMapping> getHandlerMappings(Object bean) {
        
                    try {
        
                        Field field = ReflectionUtils.findField(bean.getClass(), "handlerMappings");
                        assert field != null;
                        field.setAccessible(true);
                        return (List<RequestMappingInfoHandlerMapping>) field.get(bean);
                    } catch (IllegalArgumentException | IllegalAccessException e) {
        
                        throw new IllegalStateException(e);
                    }
                }
            };
        }
    }

#### 6、实体对象 VO 实现 ####

\# EventVO Event-事件 视图层实体对象实现

package com.lizhengi.entity.vo;
    
    import io.swagger.annotations.ApiModelProperty;
    import lombok.AllArgsConstructor;
    import lombok.Builder;
    import lombok.Data;
    import lombok.NoArgsConstructor;
    
    import java.util.List;
    
    /**
     * @author liziheng
     * @version 1.0.0
     * @description Event-事件 视图层实体对象实现
     * @date 2022-12-09 0:58 上午
     **/
    @Data
    @Builder
    @NoArgsConstructor
    @AllArgsConstructor
    public class EventVO {
        
    
        /**
         * 事件名称
         */
        @ApiModelProperty("事件名称")
        private String eventName;
    
        /**
         * 事件类型
         */
        @ApiModelProperty("事件类型")
        private String eventType;
    
        /**
         * 事件发生时间
         */
        @ApiModelProperty("事件发生时间")
        private String eventDate;
    
        /**
         * 事件地点
         */
        @ApiModelProperty("事件地点")
        private String eventLocation;
    
        /**
         * 事件人物
         *
         * @see CharacterVO
         */
        @ApiModelProperty("事件人物")
        private List<CharacterVO> characters;
    
        /**
         * 事件描述
         */
        @ApiModelProperty("事件描述")
        private String eventDescription;
    }

\# CharacterVO Character-人物 视图层实体对象实现

#### 7、controller 控制层实现 ####

\# EventController Event-事件 Controller

package com.lizhengi.controller;
    
    import com.lizhengi.entity.vo.EventVO;
    import com.lizhengi.service.impl.EventServiceImpl;
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiOperation;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RequestMethod;
    import org.springframework.web.bind.annotation.RestController;
    
    import java.util.List;
    
    /**
     * @author liziheng
     * @version 1.0.0
     * @description Event-事件 Controller
     * @date 2022-12-07 8:17 下午
     **/
    @Api(tags = "EventController")
    @RestController
    @RequestMapping("/api/lizhengi/event")
    public class EventController {
        
    
        EventServiceImpl eventService;
    
        @Autowired
        public void setEventService(EventServiceImpl eventService) {
        
            this.eventService = eventService;
        }
    
        @ApiOperation("全量获取事件信息")
        @RequestMapping(path = {
        "/list"}, method = RequestMethod.GET)
        public List<EventVO> getEventDtoList() {
        
            return eventService.getEventDtoList();
        }
    }

#### 8、控制台输出 Swagger 接口文档地址 ####

\# SwaggerPrintConfig 控制台输出 Swagger 接口文档地址

package com.lizhengi.config;
    
    import lombok.extern.slf4j.Slf4j;
    import org.springframework.boot.web.context.WebServerInitializedEvent;
    import org.springframework.context.ApplicationListener;
    import org.springframework.stereotype.Component;
    
    import java.net.Inet4Address;
    import java.net.UnknownHostException;
    
    /**
     * @author liziheng
     * @version 1.0.0
     * @description 控制台输出 Swagger 接口文档地址
     * @date 2022-12-09 3:28 上午
     **/
    @Component
    @Slf4j
    public class SwaggerPrintConfig implements ApplicationListener<WebServerInitializedEvent> {
        
        @Override
        public void onApplicationEvent(WebServerInitializedEvent event) {
        
            try {
        
                // 获取IP
                String hostAddress = Inet4Address.getLocalHost().getHostAddress();
                // 获取端口号
                int port = event.getWebServer().getPort();
                // 获取应用名
                String applicationName = event.getApplicationContext().getApplicationName();
                // 打印 swagger 文档地址
                log.info("项目启动启动成功！swagger3 接口文档地址: http://" + hostAddress + ":" + port + applicationName + "/swagger-ui/index.html");
                // 打印 swagger2 文档地址
                log.info("项目启动启动成功！swaggerUI 接口文档地址: http://" + hostAddress + ":" + port + applicationName + "/doc.html");
            } catch (UnknownHostException e) {
        
                e.printStackTrace();
            }
        }
    }

## 三、效果验证 ##

#### 1、控制台输出 ####

![image-20221209034153337][]

#### 2、Swagger-UI ####

![image-20221212163251647][]

--------------------

## 更、维护日志 ##

#### 12月12日内容更新 ####

*  将 不再维护的 swagger-bootstrap-ui 框架替换成了更新的 Knife4j；
 *  解决了因拦截器导致的 doc.html 页面出现 Whitelabel Error Page 问题。

[https_toscode.gitee.com_li_ziheng_lizhengi-samples_tree_feature_2Fspring-boot-1.0.1]: https://toscode.gitee.com/li_ziheng/lizhengi-samples/tree/feature%2Fspring-boot-1.0.1/
[https_toscode.gitee.com_li_ziheng_lizhengi-samples_tree_feature_2Fspring-boot-1.0.2]: https://toscode.gitee.com/li_ziheng/lizhengi-samples/tree/feature%2Fspring-boot-1.0.2/
[image-20221209034153337]: https://img-blog.csdnimg.cn/img_convert/109fa3c038943e62e0c9ef6fe74f489c.png
[image-20221212163251647]: https://img-blog.csdnimg.cn/img_convert/a1eb8044de15fe3edeb0a4e2a9a48796.png