• 序：介面文檔
• 1 Swagger
  • 1.1 基本信息
  • 1.2 接入步驟
• 2 Knife4j
  • 2.1 基本信息
  • 2.2 接入步驟

序：介面文檔

​ 在開發過程中，介面文檔是非常重要的一環，在 Spring Boot 中，我們可以通過集成第三方來實現介面文檔的自動生成。

​ 通過註解來描述介面，然後根據這些註解自動生成介面文檔，它不僅方便開發者查看和理解介面的功能和參數，還能幫助前後端開發協同工作，提高開發效率。

​ 常用的介面文檔，有Swagger和Knife4j，推薦Knife4j 。

• 作用
  • 方便前後端開發對接
  • 方便沉澱和維護
  • 支持線上調試、線上測試
  • 可以導出介面文檔

1 Swagger

Swagger 是一個 RESTful 介面文檔的規範和工具集，它的目標是統一 RESTful 介面文檔的格式和規範。

1.1 基本信息

• 官網

  https://swagger.io/

• Maven中央倉庫

  • 後端

    https://mvnrepository.com/artifact/io.springfox/springfox-swagger2

  • 前端

    https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui

1.2 接入步驟

• 根據maven中央倉庫，引入包

  根據SpringBoot選擇對應的版本，我的是SpringBoot版本是2.7.15

  • Swagger後端包

  io.springfox springfox-swagger2 2.9.2 ```

  • Swagger前端包

    <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>
    

• 創建配置類

  新建SwaggerConfig.java 文件

  package com.leovany.usercenter.config;
  
  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;
  
  @Configuration
  @EnableSwagger2
  public class SwaggerConfig {
  
      @Bean
      public Docket productApi() {
          return new Docket(DocumentationType.SWAGGER_2)
                  .apiInfo(apiInfo())
                  .select()
                  // 這裡一定要標註你控制器的位置
                  .apis(RequestHandlerSelectors.basePackage("com.leovany.usercenter.controller"))
                  .paths(PathSelectors.any())
                  .build();
      }
  
      /**
       * api 信息
       *
       * @return
       */
      private ApiInfo apiInfo() {
          return new ApiInfoBuilder()
                  .title("用戶中心")
                  .description("用戶中心介面文檔")
                  .termsOfServiceUrl("https://github.com/leovany")
                  .contact(new Contact("leovany", "https://github.com/leovany", "[email protected]"))
                  .version("v1.0.0")
                  .build();
      }
  
  }
  
  

• 配置路徑匹配策略

  • 如果 springboot version >= 2.6，需要添加如下配置

    spring:
    	mvc:
    		pathmatch:
        	matching-strategy: ANT_PATH_MATCHER
    

  • 原因

    Spring MVC 的路徑匹配策略是 ant-path-matcher，而 Spring Boot 2.6.x版本的預設匹配策略是 path-pattern-matcher，這就導致啟動時報錯，錯誤內容信息：

    Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException
    ...
    

• 啟動項目，輸入地址

  地址：http://localhost:8080/swagger-ui.html

  

2 Knife4j

knife4j是為Java MVC框架集成Swagger生成Api文檔的增強解決方案

2.1 基本信息

• 官網

  https://doc.xiaominfo.com/v2/index.html

• Maven中央倉庫:

  https://mvnrepository.com/artifact/com.github.xiaoymin/knife4j-spring-boot-starter

• 接入文檔

  https://doc.xiaominfo.com/v2/documentation/

2.2 接入步驟

• 根據maven中央倉庫，引入包

  根據SpringBoot選擇對應的版本，我的是SpringBoot版本是2.7.15

  <!--  https://mvnrepository.com/artifact/com.github.xiaoymin/knife4j-spring-boot-starter -->
  <dependency>
      <groupId>com.github.xiaoymin</groupId>
      <artifactId>knife4j-spring-boot-starter</artifactId>
      <version>3.0.3</version>
  </dependency>
  

• 創建配置類

  新建Knife4jConfig.java 文件

  package com.leovany.usercenter.config;
  
  import org.springframework.context.annotation.Bean;
  import org.springframework.context.annotation.Configuration;
  import org.springframework.context.annotation.Profile;
  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.EnableSwagger2WebMvc;
  
  /**
   * 自定義 Knife4j 介面文檔的配置
   */
  @Configuration
  @EnableSwagger2
  public class Knife4jConfig {
  
      @Bean(value = "defaultApi2")
      public Docket defaultApi2() {
          return new Docket(DocumentationType.SWAGGER_2)
                  .apiInfo(apiInfo())
                  .select()
                  // 項目controller的位置
                  .apis(RequestHandlerSelectors.basePackage("com.leovany.usercenter.controller"))
                  .paths(PathSelectors.any())
                  .build();
      }
  
      /**
       * api 信息
       *
       * @return
       */
      private ApiInfo apiInfo() {
          return new ApiInfoBuilder()
                  .title("用戶中心")
                  .description("用戶中心介面文檔")
                  .termsOfServiceUrl("https://github.com/leovany")
                  .contact(new Contact("leovany", "https://github.com/leovany", "[email protected]"))
                  .version("1.0.0")
                  .build();
      }
  }
  
  

• 配置路徑匹配策略

  • 如果 springboot version >= 2.6，需要添加如下配置

    spring:
    	mvc:
    		pathmatch:
        	matching-strategy: ANT_PATH_MATCHER
    

  • 原因

    Spring MVC 的路徑匹配策略是 ant-path-matcher，而 Spring Boot 2.6.x版本的預設匹配策略是 path-pattern-matcher，這就導致啟動時報錯，錯誤內容信息：

    Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException
    ...
    

• 配置是否屏蔽文檔介面

  在文件application.yml配置，生產環境註意防止暴露介面文檔（production設置為true）

  knife4j:
    # 開啟增強配置
    enable: true
    # 是否屏蔽介面文件(true=屏蔽，false=不屏蔽)
    production: false
  

• 啟動項目，輸入地址

  地址：http://localhost:8080/doc.html

  

本文由博客一文多發平臺 OpenWrite 發佈！