SpringBoot整合Knife4j接口文档生成工具

一个好的项目，接口文档是非常重要的，除了能帮助前端和后端开发人员更快地协作完成开发任务，接口文档还能用来生成资源权限，对权限访问控制的实现有很大的帮助。

这篇文章介绍一下企业中常用的接口文档工具Knife4j（基于Swagger实现）的使用。

SpringBoot整合Knife4j的步骤

创建项目

首先，通过Intellij IDEA创建一个springboot项目，命名为springboot-knife4j

修改配置

修改pom.xml

修改一下springboot的版本和java的版本（本篇文章使用springboot 2.5.9版本），然后添加knife4j的依赖。

完整的pom.xml文件内容：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.5.9</version>
        <relativePath />
    </parent>

    <groupId>cn.edu.sgu.www</groupId>
    <artifactId>springboot-knife4j</artifactId>
    <version>0.0.1-SNAPSHOT</version>

    <properties>
        <java.version>1.8</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

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

        <!--lombok-->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.18.22</version>
            <optional>true</optional>
        </dependency>

    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

修改application.yml

开启knife4j的增强模式

knife4j:
  enable: true

创建Knife4j配置类

package cn.edu.sgu.www.knife4j.config;

import com.github.xiaoymin.knife4j.spring.extension.OpenApiExtensionResolver;
import org.springframework.beans.factory.annotation.Autowired;
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.EnableSwagger2WebMvc;

/**
 * Knife4j配置类
 * @author heyunlin
 * @version 1.0
 */
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfig {

    // 指定Controller包路径（必须）
    private static final String basePackage = "cn.edu.sgu.www.knife4j.controller";
    private static final String host = "LAPTOP-0N6P8HTP";
    private static final String title = "Spring Boot整合Knife4j案例项目";
    private static final String description = title + "在线API文档";
    private static final String termsOfServiceUrl = "https://www.apache.org/licenses/LICENSE-2.0";
    private static final String contactName = "heyunlin"; // 联系人
    private static final String contactUrl = "https://gitee.com/he-yunlin";
    private static final String contactEmail = "heyl163_com@163.com";
    private static final String version = "1.0.0";

    private final OpenApiExtensionResolver openApiExtensionResolver;

    @Autowired
    public Knife4jConfig(OpenApiExtensionResolver openApiExtensionResolver) {
        this.openApiExtensionResolver = openApiExtensionResolver;
    }

    @Bean
    public Docket docket() {
        String groupName = "1.0.0";

        return new Docket(DocumentationType.SWAGGER_2)
                .host(host)
                .apiInfo(apiInfo())
                .groupName(groupName)
                .select()
                .apis(RequestHandlerSelectors.basePackage(basePackage))
                .paths(PathSelectors.any())
                .build()
                .extensions(openApiExtensionResolver.buildExtensions(groupName));
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(title)
                .description(description)
                .termsOfServiceUrl(termsOfServiceUrl)
                .contact(new Contact(contactName, contactUrl, contactEmail))
                .version(version)
                .build();
    }

}

创建控制器类

新建UserController，类上使用@Api注解，在方法上使用@ApiOpration注解

package cn.edu.sgu.www.knife4j.controller;

import cn.edu.sgu.www.knife4j.dto.UserLoginDTO;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author heyunlin
 * @version 1.0
 */
@Api(tags = "用户管理")
@RestController
@RequestMapping("/user")
public class UserController {

    @ApiOperation("登录认证")
    @PostMapping("login")
    public String login(UserLoginDTO userLoginDTO) {
        return "登录成功";
    }

}

创建传输对象实体类

package cn.edu.sgu.www.knife4j.dto;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

/**
 * @author heyunlin
 * @version 1.0
 */
@Data
@ApiModel
public class UserLoginDTO {

    @ApiModelProperty(value = "用户名", required = true)
    private String username;

    @ApiModelProperty(value = "密码", required = true)
    private String password;
}

除此之外，Knife4j还提供了其他的注解：

@ApiParam

@ApiImplicitParam

package cn.edu.sgu.www.knife4j.controller;

import cn.edu.sgu.www.knife4j.dto.UserLoginDTO;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author heyunlin
 * @version 1.0
 */
@Api(tags = "用户管理")
@RestController
@RequestMapping("/user")
public class UserController {

    @ApiOperation("登录认证")
    @PostMapping("/login")
    public String login(UserLoginDTO userLoginDTO) {
        return "登录成功~";
    }

    @ApiOperation("用户注册")
    @PostMapping("/register")
    public String register(
            @ApiParam(value = "用户名",  required = true) String username,
            @ApiParam(value = "密码",  required = true) String password) {
        return "注册成功~";
    }

    @ApiOperation("保存用户")
    @PostMapping("/save")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "用户名", allowEmptyValue = true),
            @ApiImplicitParam(name = "password", value = "密码", allowEmptyValue = true)
    })
    public String save(
            @ApiParam(value = "用户名",  required = true) String username,
            @ApiParam(value = "密码",  required = true) String password) {
        return "保存成功~";
    }

}

最后，启动项目，访问localhost:端口号/doc.html

好了，文章就分享到这里了，代码已经上传到gitee，可按需获取~

Spring Boot整合Knife4j案例项目https://gitee.com/he-yunlin/springboot-knife4j.git