【Spring Boot】如何集成Swagger

1. Swagger简单介绍
   1. Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。功能主要包含以下几点：
      1. 可以使前后端分离开发更加方便，有利于团队协作
      2. 接口文档可以在线自动生成，有利于降低后端开发人员编写接口文档的负担
      3. 可以进行接口功能测试
   2. 我们使用Swagger只需要按照它的规范去定义接口及接口相关的信息，再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档以及在线接口调试页面等等
2. knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案，接下来我们就在spring boot项目中集成knife4j。
3. spring boot项目中使用knife4j框架
   1. 首先我们在maven项目的pom.xml文件中导入knife4j的坐标

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

   2. 导入knife4j的相关配置类
      1. 因为是spring mvc的集成，所以我们将创建一个WebMvcConfig类，然后在里面加入相关的bean声明就可以了
         1. 在配置类上加上@EnableSwagger2、@EnableKnife4j注解，以便开启Swagger和Knife4j的功能
         2. 在配置类中声明一个Docket类型的bean, 通过该bean来指定生成文档的相关信息
         3. 由于Swagger生成的在线文档中，涉及到很多静态资源，这些静态资源需要添加静态资源映射，否则接口文档页面无法访问。因此需要在 WebMvcConfig类中的addResourceHandlers方法中增加如下配置

            1.     @Override
                   protected void addResourceHandlers(ResourceHandlerRegistry registry) {
                       log.info("开始进行静态资源映射...");
                       // 添加Swagger生成的在线文档的相关静态资源映射
                       registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
                       registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
                   }

      2. package com.app.studypro.config;
         
         import com.app.studypro.common.JacksonObjectMapper;
         import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
         import lombok.extern.slf4j.Slf4j;
         import org.springframework.context.annotation.Bean;
         import org.springframework.context.annotation.Configuration;
         import org.springframework.http.converter.HttpMessageConverter;
         import org.springframework.http.converter.json.MappingJackson2HttpMessageConverter;
         import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
         import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
         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;
         
         import java.util.List;
         
         /**
          * Spring mvc的配置设定
          *
          * @author Administrator
          */
         @Slf4j
         @Configuration
         @EnableSwagger2
         @EnableKnife4j
         public class WebMvcConfig extends WebMvcConfigurationSupport {
         
             @Override
             protected void extendMessageConverters(List<HttpMessageConverter<?>> converters) {
                 log.info("扩展消息转换器，自定义添加 {} 消息转化器到spring mvc中", JacksonObjectMapper.class);
                 // 创建消息转换器对象
                 MappingJackson2HttpMessageConverter messageConverter = new MappingJackson2HttpMessageConverter();
                 // 设置对象转换器，底层使用Jackson将Java对象转为json
                 messageConverter.setObjectMapper(new JacksonObjectMapper());
                 // 将上面的消息转换器对象追加到mvc框架的转换器集合中，将其放在转换器集合的首个位置
                 converters.add(0, messageConverter);
             }
         
             @Bean
             public Docket createRestApi() {
                 // 创建api文档信息
                 ApiInfo apiInfo = new ApiInfoBuilder()
                         // 设置api文档标题
                         .title("学习操作项目")
                         // 设置api文档的版本
                         .version("1.0")
                         // 设置api文档的描述信息
                         .description("学习操作项目接口文档").build();
         
                 // 文档类型
                 return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo).select()
                         // Docket声明时，指定一个包扫描的路径，该路径指定的是Controller所在包的路径。
                         // 因为Swagger在生成接口文档时，就是根据这里指定的包路径，自动的扫描该包下的@Controller，@RestController，@RequestMapping等SpringMVC的注解，依据这些注解来生成对应的接口文档
                         .apis(RequestHandlerSelectors.basePackage("com.app.studypro.controller")).paths(PathSelectors.any()).build();
             }
         
             /**
              * 静态资源映射
              *
              * @param registry 资源处理器
              */
             @Override
             protected void addResourceHandlers(ResourceHandlerRegistry registry) {
                 log.info("开始进行静态资源映射...");
                 // 添加Swagger生成的在线文档的相关静态资源映射
                 registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
                 registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
             }
         
         }
         

   3. 若系统中存在授权才可以请求的路径filter或者拦截器，则需要将下列路径在系统中放行。这样将Swagger及Knife4j相关的静态资源直接放行之后，我们才可以免授权方式直接访问接口文档的页面。放行的url如下所示

      1. "/doc.html",
         "/webjars/**",
         "/swagger-resources",
         "/v2/api-docs"

4. 查看接口文档信息
   1. 我们根据上面的方式集成配置之后，那么我们的项目集成Swagger及Knife4j就已经完成了，接下来我们可以启动我们的项目，然后访问接口文档，本地的访问链接为：http://127.0.0.1:8080/doc.html
   2. 
   3. 通过接口文档我们可以看出，我们所有的Controller中提供的所有的业务增删改查的接口，全部都已经自动生成了，并且我们通过接口文档可以看到请求的url、请求方式、请求参数、请求实例、响应的参数，响应的示例。 同时我们也可以通过这份在线的接口文档，对接口进行测试
   4. 如果我们部分的接口需要系统授权之后才可以访问，那么我们在调用这些接口时，需要先调用获取授权的方法，然后再调用需要授权的接口，这样才可以正常的访问授权接口
   5. Knife4j还支持离线文档，对接口文档进行下载，支持下载的格式有：markdown、html、word、openApi
      1.