Spring Boot 1.5.8集成Swagger2 + YApi —— 集成Swagger2

前言

受新型冠状病毒的影响，在家像猪一样不是睡就是吃，闲着就学着用下Swagger和YApi，特将这几天的学习成果写成了这系列的文章，希望能对大家有所帮助。武汉加油，中国加油！

Spring Boot 1.5.8集成Swagger2 + YApi —— 集成Swagger2
Spring Boot 1.5.8集成Swagger2 + YApi —— Swagger常用注解说明
Spring Boot 1.5.8集成Swagger2 + YApi —— 部署安装mongoDB
Spring Boot 1.5.8集成Swagger2 + YApi —— 部署安装YApi（在线安装）
Spring Boot 1.5.8集成Swagger2 + YApi —— 部署安装YApi（离线安装）
Spring Boot 1.5.8集成Swagger2 + YApi —— swagger接口信息导入YApi

---

前后端项目分离之后，前端和后端的项目开始由不同的成员来进行开发。为了减少成员之间的沟通成本，一个好的Api文档就变得尤为重要。

如果Api文档完全由后端开发成员手动编辑和发布，随着开发的推进，接口变得原来越多，及时地更新和发布文档的工作将变得极其的复杂和占用时间，不利于项目的进展。

Swagger的产生就解决了如上的问题，集成Swagger后，后端开发成员只需要编写少量的注释即可在线生成清晰明朗的Api文档供前端开发成员使用，十分的方便。

下面开始介绍Sping Boot 1.5.8如何集成Swagger和YApi

一、maven增加依赖

在pom.xml的dependencies标签下，增加如下依赖：

<!--swagger-->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.7.0</version>
</dependency>
<!--swagger 官方ui-->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.7.0</version>
</dependency>

二、编写Swagger配置类

新建一个java文件，编写Swagger的启动配置类，代码如下：

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger配置类
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    private Logger logger = LoggerFactory.getLogger(SwaggerConfig.class);

    @Bean
    public Docket createRestApi() {
        logger.info("SwaggerConfig createRestApi 构建REST API");
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ai.module.main")) // Controller所在包(api文档扫描范围)
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        logger.info("SwaggerConfig apiInfo API信息");
        return new ApiInfoBuilder()
                .title("XXX项目api文档")  // 标题
                .description("api文档")  // 描述
                .version("1.0") // 版本
                .contact(new Contact("XXX", "url", "email")) // 联系人信息
                .build();
    }

}

RequestHandlerSelectors.basePackage()配置的是controller所在的包路径，可以通过控制这个参数来控制自动生成的api文档的范围，不希望展示在自动生成的api文档上的controller可以放到所配置的包路径之外

配置好后，启动项目，即可通过浏览器访问如下链接访问到Swagger的页面：

http://localhost:项目启动端口/项目名/swagger-ui.html

页面效果如下：

三、集成增强UI

Swagger官方提供的UI页面结构不是很直观，Swagger-Bootstrap-UI是一套基于Swagger 的前端UI，采用jQuery+bootstrap实现，将Swagger 默认的上下结构的菜单风给改成了主流的左右菜单风格，让其看起来更清晰明了。

Swagger-Bootstrap-UI配置方法：

在pom.xml新增一个依赖即可：

<!--swagger bootstrap增强ui-->
<dependency>
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>swagger-bootstrap-ui</artifactId>
	<version>1.9.3</version>
</dependency>

注意：

1. 新增之后，使用maven的clean指令清理一下项目，笔者在集成该UI之后碰到过打包项目失败的情况，使用maven的clean指令后就解决了问题
2. Swagger官方UI可以弃用了，直接在pom.xml上注释掉Swagger官方ui的依赖

配置好后，启动项目，即可通过浏览器访问如下链接访问到Swagger增强UI的页面：

http://localhost:项目启动端口/项目名/doc.html

页面效果如下：

怎么样，是不是美观很多

四、配置生产环境屏蔽Swagger

Swagger是开发人员在开发过程中使用的工具，发布到生产环境的时候肯定是要屏蔽掉的，如果使用Spring Boot框架，只需在application.properties或者application.yml配置文件中配置一下即可：

application.properties：
swagger.production=true

application.yml：

swagger:
  production: true

添加如上配置之后，Swagger相关页面就无法访问了：

平时开发，只需要将该配置置为false，即可正常使用Swagger