集成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

登录认证