在 Spring Boot 项目中使用 Knife4J 生成接口 API 文档

李少兄

于 2024-08-18 22:57:40 发布

阅读量282

点赞数 3

分类专栏： Java 文章标签： spring boot 后端 java

本文链接：https://blog.csdn.net/wenxuankeji/article/details/141307179

版权

Java 专栏收录该内容

82 篇文章 2 订阅

订阅专栏

前言

API 文档是现代软件开发中不可或缺的一部分，它能够帮助开发者了解应用程序的各个接口是如何工作的。在众多 API 文档工具中，Swagger 是最流行的一个，而 Knife4J 则是基于 Swagger 2 构建的一个强大的 UI 层，提供了更丰富的功能和更好的用户体验。

本篇文章将详细介绍如何在 Spring Boot 项目中集成 Knife4J，并生成高质量的 API 文档。

准备环境

为了确保一切顺利，我们需要确认以下条件已满足：

已安装 JDK 1.8 或更高版本。
已安装 Maven 或 Gradle。
已有一个基本的 Spring Boot 项目。

步骤一：添加依赖

在 pom.xml 文件中添加必要的依赖。确保你已经添加了 Swagger 2 的依赖，因为 Knife4J 是基于 Swagger 2 的。

<!-- 添加 Swagger 2 的依赖 -->
<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>

<!-- 添加 Knife4J 的依赖 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.4</version> <!-- 请使用最新的版本 -->
</dependency>

步骤二：配置 Swagger

接下来需要配置 Swagger，以便它可以扫描你的控制器并生成 API 文档。这可以通过创建一个新的 Java 配置类来实现。

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("your.package.controller")) // 指定要扫描的控制器包
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot 使用 Knife4J 生成 API 文档示例")
                .description("这是一个使用 Spring Boot 和 Knife4J 自动生成 API 文档的示例项目")
                .version("1.0")
                .build();
    }
}

注意事项

替换 "your.package.controller" 为你的实际 Controller 包路径。
如果你的应用中有多个不同的模块，可以考虑使用多个 Docket 实例，每个实例对应一个模块。

步骤三：自定义文档

虽然默认情况下 Swagger 与 Knife4J 就能很好地工作，但你还可以进一步自定义文档，使其更符合你的需求。

自定义全局参数

@Bean
public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("your.package.controller"))
            .paths(PathSelectors.any())
            .build()
            .globalOperationParameters(parameters()); // 添加全局参数
}

private List<Parameter> parameters() {
    ParameterBuilder tokenPar = new ParameterBuilder();
    List<Parameter> pars = new ArrayList<>();
    tokenPar.name("Authorization").description("令牌").modelRef(new ModelRef("string"))
            .parameterType("header").required(false).build();
    pars.add(tokenPar.build());
    return pars;
}

忽略特定的 Controller 或者 Method

@Bean
public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("your.package.controller"))
            .apis(RequestHandlerSelectors.not(RequestHandlerSelectors.basePackage("your.package.ignore"))) // 忽略指定的包
            .paths(PathSelectors.any())
            .build();
}

自定义响应消息

@Bean
public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("your.package.controller"))
            .paths(PathSelectors.any())
            .build()
            .useDefaultResponseMessages(false) // 不使用默认的响应消息
            .globalResponseMessage(RequestMethod.GET, newArrayList(
                    new ResponseMessageBuilder().code(401).message("未授权").build(),
                    new ResponseMessageBuilder().code(403).message("禁止访问").build(),
                    new ResponseMessageBuilder().code(404).message("找不到资源").build()));
}

自定义安全方案

@Bean
public Docket createRestApi() {
    SecurityScheme apiKey = new ApiKey("apiKey", "Authorization", "header");
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .securitySchemes(Arrays.asList(apiKey))
            .securityContexts(Arrays.asList(securityContext()))
            .select()
            .apis(RequestHandlerSelectors.basePackage("your.package.controller"))
            .paths(PathSelectors.any())
            .build();
}

private SecurityContext securityContext() {
    return SecurityContext.builder()
            .securityReferences(defaultAuth())
            .forPaths(PathSelectors.regex("/anyPath.*"))
            .build();
}

List<SecurityReference> defaultAuth() {
    AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
    AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
    authorizationScopes[0] = authorizationScope;
    return Arrays.asList(new SecurityReference("apiKey", authorizationScopes));
}

步骤四：测试 Knife4J

启动你的 Spring Boot 项目后，访问以下 URL 来查看 Knife4J 文档页面：

http://localhost:8080/doc.html

Knife4J 默认会覆盖 Swagger UI 的界面，所以不需要额外的配置。如果你想要同时启用 Swagger UI 和 Knife4J UI，可以通过以下方式配置：

@Bean
public Docket docketForSwaggerUi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("swagger") // 设置 Swagger UI 的分组名称
            .enable(true) // 是否启用 Swagger UI
            .select()
            .apis(RequestHandlerSelectors.basePackage("your.package.controller"))
            .paths(PathSelectors.any())
            .build();
}

这样你就可以同时访问 Swagger UI（http://localhost:8080/swagger-ui.html）和 Knife4J UI（http://localhost:8080/doc.html）。

步骤五：定制样式

Knife4J 提供了一些自定义样式的方法，比如你可以更改主题颜色，或者修改文档的标题等。这些都可以通过配置类中的 Docket 配置来完成。

@Bean
public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("your.package.controller"))
            .paths(PathSelectors.any())
            .build()
            .groupName("group1") // 分组名称
            .pathMapping("/") // 路径映射
            .apiInfo(apiInfo());
}

private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
            .title("Spring Boot 使用 Knife4J 生成 API 文档示例")
            .description("这是一个使用 Spring Boot 和 Knife4J 自动生成 API 文档的示例项目")
            .version("1.0")
            .termsOfServiceUrl("http://example.com/terms")
            .contact(new Contact("Your Name", "http://example.com", "your.email@example.com"))
            .license("Apache License Version 2.0")
            .licenseUrl("https://www.apache.org/licenses/LICENSE-2.0")
            .build();
}