Swagger2 | 01. 配置并使用Swagger2

0. 使用的项目名字：test_spring_boot

模块名字：test_swagger

传送门 == 》码云仓库

1. 添加MAVEN依赖

前言：此处MAVEN依赖和其他文章略有不同，这样导入依赖能解决一个Swagger2在2.9.2版本之后一直存在的BUG。详情可见传送门：

传送门 == 》解决Swagger2报错：For input string: ““

1.1. 外源的Swagger UI美化：knife4j

        <!--        开始：01. swagger依赖-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
            <exclusions>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-annotations</artifactId>
                </exclusion>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-models</artifactId>
                </exclusion>
            </exclusions>
        </dependency>

        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.5.21</version>
        </dependency>

        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.21</version>
        </dependency>

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>2.0.4</version>
        </dependency>
        <!--        结束：01. swagger依赖-->

1.2. 原生Swagger（教程使用原生示例）

        <!--        开始：01. swagger依赖-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
            <exclusions>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-annotations</artifactId>
                </exclusion>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-models</artifactId>
                </exclusion>
            </exclusions>
        </dependency>

        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.5.21</version>
        </dependency>

        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.21</version>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!--        结束：01. swagger依赖-->

2. 配置Swagger2：

2.1. 基本配置

在项目下新建config包，新建SwaggerConfig.java，随后在类代码上加入注解：

@Configuration		//高级的Component注解，加入到IOC容器的同时，还配置到注解中
@EnableSwagger2		//开启Swagger2
public class SwaggerConfig

2.2. 使用Swagger2

在启动服务器后，访问该url即可：

localhost/swagger-ui.html

如果使用knife4j，那么访问url为：

localhost/doc.html

2.3. 进阶配置

2.3.1. 整体代码

@Configuration      //高级的@Component注解，加入IOC容器的同时，还配置到注解中
@EnableSwagger2     //开启swagger2
public class SwaggerConfig {
// --01.设置一会儿要用于判断的环境--------------------------------------------------------------------------------
   Profiles profiles = Profiles.of("devXYX","devSHR");

// --02.配置swagger文档的信息apiInfo-----------------------------------------------------------------------------
   private ApiInfo apiInfoForXYX() {
      //作者信息
      Contact contact = new Contact(
            //作者姓名
            "xyx",
            //作者主页地址
            "https://i.csdn.net/#/user-center/profile?spm=1001.2014.3001.5516",
            //作者邮箱
            "xyx2112672663@163.com");

      return new ApiInfo(
            //文档标题
            "xyx的SwaggerAPI文档",
            //文档描述
            "潜心静学，沉淀自我",
            //文档版本
            "v1.0",
            //使用协议的地址
            "xxx",
            //作者信息
            contact,
            //许可证
            "Apache 2.0",
            //许可证地址
            "http://www.apache.org/licenses/LICENSE-2.0",
            new ArrayList<>()
      );
   }

// --03.配置swagger的docket-----------------------------------------------------------------------------
   @Bean
   //参数environment表示当前的环境
   public Docket docketForXYX(Environment environment) {
      //你负责的这个Artifact的名字
      String artifactName = "test_swagger";

      return new Docket(DocumentationType.SWAGGER_2).
            apiInfo(apiInfoForXYX())
            //设置组名
            .groupName("XYX")
            //通过environment.acceptProfiles判断目前是否处在profiles中设定的环境之下
            //如果是，返回true，则会开启swagger
            .enable(environment.acceptsProfiles(profiles))
            //指定要扫描的包，一般是controller包
            //除了basePackage以外，还可以有（虽然这两个都没什么卵用）：
            //any()：扫描全部
            //none()：都不扫描
            .select().apis(RequestHandlerSelectors.basePackage("com.eshang." + artifactName + ".controller"))
            .build();
   }

2.3.2. 局部代码剖析

（1） 获取profiles：用以第三步判断环境

//  --01.设置一会儿要用于判断的环境--------------------------------------------------------------------------------
   Profiles profiles = Profiles.of("devXYX");

参数就写所有启用swagger2的环境名，参数个数可变

（2） 设置文档信息：用以第三步配置

// --02.配置swagger文档的信息apiInfo-----------------------------------------------------------------------------
   private ApiInfo apiInfoForXYX() {
      //作者信息
      Contact contact = new Contact(
            //作者姓名
            "xyx",
            //作者主页地址
            "https://i.csdn.net/#/user-center/profile?spm=1001.2014.3001.5516",
            //作者邮箱
            "xyx2112672663@163.com");

      return new ApiInfo(
            //文档标题
            "xyx的SwaggerAPI文档",
            //文档描述
            "潜心静学，沉淀自我",
            //文档版本
            "v1.0",
            //使用协议的地址
            "xxx",
            //作者信息
            contact,
            //许可证
            "Apache 2.0",
            //许可证地址
            "http://www.apache.org/licenses/LICENSE-2.0",
            new ArrayList<>()
      );
   }

（3） 用docket配置Swagger2

//  --03.配置swagger的docket-----------------------------------------------------------------------------
   @Bean
   //参数environment表示当前的环境
   public Docket docketForXYX(Environment environment) {
      //你负责的这个Artifact的名字
      String artifactName = "test_swagger";

      return new Docket(DocumentationType.SWAGGER_2).
            apiInfo(apiInfoForXYX())
            //设置组名
            .groupName("XYX")
            //通过environment.acceptProfiles判断目前是否处在profiles中设定的环境之下
            //如果是，返回true，则会开启swagger
            .enable(environment.acceptsProfiles(profiles))
            .select()
            //指定要扫描的包，一般是controller包
            //除了basePackage以外，还可以有（虽然这两个都没什么卵用）：
            //any()：扫描全部
            //none()：都不扫描
            .apis(RequestHandlerSelectors.basePackage("com.eshang." + artifactName + ".controller"))
            .build();
   }

tips:请务必在docket上加上@Bean注解！

其中，有：

1）★★★★★

apiInfo(apiInfoForXYX())

参数包含了这份swagger文档的基本信息（来自于第二步）

2）★★★★★

.groupName("XYX")

开发组名，代表这是属于哪一个小组开发的

3）★★★★★

.enable(environment.acceptsProfiles(profiles))

参数是一个boolean值，为true则开启Swagger2
此处的参数值中：
profiles来自于第一步，设置了开启Swagger2的环境名

environment.acceptsProfiles(profiles)

这个代码就是.enable的参数，它的返回值是一个boolean值
检测当前所处环境是否在第一步设置的范围之内，如果是则返回true，此时便开启Swagger2

4）★★★★★

.select().apis(RequestHandlerSelectors.basePackage(“com.eshang.”+ artifactName +“.controller”))

basePackage指定要扫描的包。
这里的artifactName是在前面设置的属性，只要正确填写包名就行

5）★★★★★

.build()

工厂模式，加上即可