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