SpringBoot集成Swagger(根據源碼深入學習Swagger的用法)

從源碼層面講解Swagger的用法，快速了解掌握Swagger

簡介

Swagger 是一個規范且完整的框架，用於生成、描述、調用和可視化 Restful 風格的 Web 服務。 自動生成html文檔。官網： https://swagger.io/

優勢

1. 支持 API 自動生成同步的在線文檔 。API文檔和API定義同步更新
2. 提供 Web 頁面在線測試 API ，不需要再下載postman使用
3. 支持多種語言

使用步驟

導入依賴

  <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>2.9.2</version>
  </dependency>
  <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger-ui</artifactId>
      <version>2.9.2</version>
  </dependency>

主程序類上加上@EnableSwagger2注解

@SpringBootApplication
@EnableSwagger2 
public class SwaggerApplication {
    public static void main(String[] args) {
        SpringApplication.run(SwaggerApplication.class, args);
    }
}

訪問API在線文檔

http://localhost:8080/swagger-ui.html#/

為什么訪問上面的頁面，可能很多人存在疑問。一切都是根據源碼來的。在Swagger-UI的包下

以上是Swagger的最簡單用法，但是在API在線文檔頁面我們想修改一些配置，如分組信息，Swagger信息，需要配置Swagger

配置Swagger

Swagger 的Docket的bean實例

我們可以通過Swagger的源碼理解上圖中的Swagger信息部分是如何出來的，同時我們知道如何修改。

Docket對象

ApiInfo對象

配置Swagger的默認信息

  private ApiInfo apiInfo() {
        Contact contact = new Contact("小K", "https://github.com/kong0827", "[e-mail]");
        return new ApiInfo("小K的Swagger接口文檔",
                "每天學習一丟丟，每天進步一點點",  // 描述
                "1.0",
                "https://github.com/kong0827",
                contact,                                   // 作者信息
                "Apache 2.0",
                "ttps://github.com/kong0827",
                new ArrayList()
        );
    }

配置Swagger的Docket的bean實例

 @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("開發小組名稱")
                .select()
            	// 配置要掃描接口的方式
                .apis(RequestHandlerSelectors.any())
                // 過濾什么路徑 過濾只含有kong下面的請求
                // .paths(PathSelectors.ant("/kong/**"))
                .build();
    }

配置swagger是否啟動

默認啟動

  @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("開發小組名稱")
                .enable(true)
                .select()
                // 配置要掃描接口的方式
                .apis(RequestHandlerSelectors.any())
                // 過濾什么路徑 過濾只含有kong下面的請求
                .paths(PathSelectors.ant("/kong/**"))
                .build();
    }

問題：Swagger在生產環境使用，在發布的時候不使用

1. 通過判斷當前的環境
   @Bean
   public Docket docket(Environment environment) {
   // 設置要顯示的Swagger環境
   Profiles profiles = Profiles.of("dev", "test");
   // 通過Environment.acceptsProfiles 判斷是否處在自己設定的環境中
   boolean enable = environment.acceptsProfiles(profiles);

       return new Docket(DocumentationType.SWAGGER_2)
               .apiInfo(apiInfo())
               .groupName("開發小組名稱")
               .enable(enable)
               .select()
               // 配置要掃描接口的方式
               .apis(RequestHandlerSelectors.any())
               // 過濾什么路徑 過濾只含有kong下面的請求
               .paths(PathSelectors.ant("/kong/**"))
               .build();
   }
   

2. 采用屬性注入

   	/**
        * 設置是否顯示接口文檔
        */
       @Value("${swagger.enable}")
       private boolean enable;