集成Knife4j

knife4j 目前主要支持以 Java 開發為主

Spring Boot 基礎實戰:

• Spring Boot 2.5.0
• Knife4j 2.0.9
• Maven 3.6.3
• JDK 1.8

注意： 使用 Knife4j 2.0.6+ 版本，Spring Boot 的版本要求 2.2.x+

1、Knife4j 依賴引入

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.9</version>
</dependency>

2、Knife4j 配置

開啟增強功能及基本的登錄認證：

knife4j:
  # 開啟增強
  enable: true
  # 開啟登錄認證
  basic:
    enable: true
    username: test
    password: test

支持個性化配置項，如接口地址、接口描述屬性、UI 增強等個性化配置功能：

/**
 * Knife4j 配置類
 */
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {

    @Bean(value = "defaultDocket")
    public Docket defaultDocket() {
        // 聯系人信息
        Contact contact = new Contact("聯系人信息", "https://www.javastack.cn", "[e-mail]");

        // 創建 Docket
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        .title("Knife4j 測試")
                        .description("Knife4j Test")
                        .termsOfServiceUrl("https://www.javastack.cn")
                        .contact(contact)
                        .version("1.0")
                        .build())
                .groupName("1.x")
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.javastack.springboot.knife4j.api"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

}

3、新增測試接口

兩個測試接口，一個登錄（POST），一個（GET）。

/**
 * Knife4j
 */
@Api(tags = "測試模塊")
@RestController
public class Knife4jController {

    /**
     * Knife4j 測試接口
     */
    @ApiImplicitParam(name = "name", value = "名稱", required = true)
    @ApiOperation(value = "123")
    @ApiOperationSupport(order = 2, author = "456")
    @GetMapping("/knife4j/hi")
    public ResponseEntity<String> hello(@RequestParam(value = "name") String name) {
        return ResponseEntity.ok("Hi:" + name);
    }

    /**
     * Knife4j 測試接口
     */
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "用戶名", required = true),
            @ApiImplicitParam(name = "password", value = "密碼", required = true)
    })
    @ApiOperation(value = "接口登錄！")
    @ApiOperationSupport(order = 1, author = "456")
    @PostMapping("/knife4j/login")
    public ResponseEntity<String> login(@RequestParam(value = "username") String username,
                                        @RequestParam(value = "password") String password) {
        if (StringUtils.isNotBlank(username) && "javastack".equals(password)) {
            return ResponseEntity.ok("登錄成功:" + username);
        }
        return ResponseEntity.ok("用戶名或者密碼有誤:" + username);
    }

}

上面為了支持接口順序和接口作者，使用了 Knife4j 的 @ApiOperationSupport 注解，其他的均為 Swagger 自帶的注解，從該目錄下看還支持下面的注解：

更多可去官網進行學習。

完整的 Demo 代碼就不一一帖了，本節教程所有實戰源碼已上傳到這個倉庫：

https://github.com/javastacks/spring-boot-best-practice

4、Knife4j 測試

啟動應用，打開 Knife4j 文檔頁：

http://localhost:8080/doc.html

登錄認證