項目引入Swagger及使用姿勢

1.導入pom依賴

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
     <groupId>com.github.xiaoymin</groupId>
     <artifactId>knife4j-spring-boot-starter</artifactId>
     <version>2.0.2</version>
</dependency>

2.添加swagger配置類

package com.demo.config;

import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;
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;

import java.util.HashSet;

/**
 * <p>
 * swagger頁面展示的配置
 * </p>
 *
 * @author Toby
 * @since 2020/5/13
 */
@Configuration
@EnableSwagger2
@EnableKnife4j
public class Swagger2Configuration {

    @Bean
    public Docket createRestApi() {
        HashSet<String> contentType = new HashSet<>(1);
        contentType.add("application/json");
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .consumes(contentType)
                .produces(contentType)
                .select()
            	// 掃描包路徑
                .apis(RequestHandlerSelectors.basePackage("com.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("xxx-api文檔")
                .description("xxx-xx模塊api文檔")
                .version("1.0")
                .contact(new Contact("xxx項目組","","[e-mail]"))
                .build();
    }
    

}

注：basePackage要改為項目對應的controller目錄路徑，使用增強功能的話，需要在配置類上加@EnableKnife4j注解，並且在UI界面的個性化設置中開啟增強功能。具體增強功能請移步至最后自行查看文檔。

3.查看UI界面

啟動項目后，在瀏覽器輸入http://${host}😒{port}/doc.html

4.項目中可能會用到的增強功能

• 自定義文檔

  在resource目錄下新建markdown文件夾，在目錄下新建.md結尾的file即可。在application.yml中加入以下配置

  knife4j:
    markdowns: classpath:markdown/*
  

  注意：自定義文檔說明必須以.md結尾的文件,其他格式文件會被忽略

• 訪問權限控制-生產環境屏蔽Swagger所有資源接口

  之前的項目如果想在正式環境配置中屏蔽Swagger資源的話，是取的spring.profiles.active運行環境作判斷，現在只需要在正式的application.yml中加入以下配置即可。

  knife4j:
    production: true
  

• 訪問頁面加權控制

  登錄需要賬號密碼，提供簡單的basic認證功能，在application.yml中加入以下配置即可。

  knife4j:
    ## 開啟Swagger的Basic認證功能,默認是false
    basic:
      enable: true
    ## Basic認證用戶名
      username: admin
    ## Basic認證密碼
      password: 123456
  

4.注意事項

• 依賴變更

  ui前端界面顯示的依賴更改，com.github.xiaoymin下的springfox-swagger-ui最終版本為1.9.6，之后版本包名更改為knife4j，不同框架集成方式的pom依賴自行查看原文文檔。

• api分組相關，Docket實例不能延遲加載（目前應該用不到，具體多少個算多也不清楚，知道即可。）

  springfox默認會把所有api分成一組，這樣訪問時會在同一個頁面里加載所有api列表。這樣，如果系統稍大一點，api稍微多一點，頁面就會出現假死的情況，所以很有必要對api進行分組。api分組，定義多個RestApi即可，通過groupName作區分。

5.文檔地址

knife4j使用教程：https://doc.xiaominfo.com/knife4j/

GitHub地址：https://github.com/xiaoymin/swagger-bootstrap-ui