利用Knife4j注解实现Java生成接口文档

逐梦苍穹

已于 2024-05-03 14:41:11 修改

阅读量2.6k

点赞数 19

文章标签： java 接口文档 knife4j swagger

于 2024-01-29 23:04:26 首次发布

本文链接：https://blog.csdn.net/qq_60735796/article/details/135922956

版权

本文介绍了Knife4j，一款基于Swagger的开源工具，它简化了API文档的创建、测试和调试过程。文章详细讲解了如何在SpringBoot项目中集成Knife4j，以及其主要注解的使用，如@Api、@ApiResponses、@ApiOperation等，帮助开发者更好地管理API文档。

摘要由CSDN通过智能技术生成

🍃作者介绍：双非本科大三网络工程专业在读，阿里云专家博主，专注于Java领域学习，擅长web应用开发、数据结构和算法，初步涉猎Python人工智能开发和前端开发。
🦅主页：@逐梦苍穹
📕项目专栏：您的一键三连，是我创作的最大动力🌹

1、简介

Knife4j 是一款基于 Swagger 的开源 API 文档生成工具，它提供了一套简洁的界面来展示和测试你的 API。Knife4j 使得 API 文档的编写、查看和测试变得更加方便，同时支持在线调试接口。
以下是 Knife4j 的一些主要特性和优势：

基于 Swagger： Knife4j 是 Swagger 的一个增强版本，它利用 Swagger 注解来生成 API 文档，能够自动生成接口文档、测试接口等信息。
美观的界面： Knife4j 提供了一个直观、美观的界面，使得 API 文档更易于阅读和理解。它支持显示接口的请求和响应参数、响应示例、参数类型等详细信息。
在线调试： Knife4j 允许用户在界面中直接进行 API 接口的测试和调试，无需额外的工具。你可以在文档页面直接输入参数，模拟请求，并查看实时的响应。
接口分组：可以将接口按照业务逻辑或其他标准进行分组，使得文档更具有组织性和可读性。
代码生成： Knife4j 支持通过在线界面生成前端调用 API 的代码片段，包括 Java、Spring Cloud Feign、JavaScript 等。
易于集成： Knife4j 提供了简单的集成方式，支持 Spring Boot 项目，只需要引入相应的依赖即可。
自定义配置： Knife4j 提供了一系列的配置选项，可以根据项目的需求进行自定义配置，以满足不同场景的需求。

总体而言，Knife4j 是一个强大、易用的 API 文档生成工具，适用于 Java 和 Spring Boot 项目，使得 API 的设计、测试和文档生成更加便捷。

2、生成文档

在springboot工程中，生成后端接口文档是非常重要的。
首先是引入依赖：

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

如果springboot启动的时候显示：
应用程序上下文对象异常-启动bean“documentationPluginsBootstrapper”失败，则导入：

<dependency>
    <groupId>org.hibernate.validator</groupId>
    <artifactId>hibernate-validator</artifactId>
    <version>6.0.18.Final</version>
</dependency>

或在父工程的pom.xml文件中添加：

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

接下来需要编写一个配置类，初始化接口文档的配置：

package com.xzl.user.config;

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import lombok.extern.slf4j.Slf4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration;
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;

/**
 * @author 逐梦苍穹
 * @date 2024/5/3 14:12
 */
@Configuration
@Slf4j
@EnableSwagger2
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
// TODO BeanValidatorPluginsConfiguration.class
public class knife4jConfiguration {
    /**
     * 通过knife4j生成接口文档
     * @return
     */
    @Bean
    public Docket docket() {
        log.info("开始生成接口文档...");
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("")
                .version("1.0")
                .description("")
                .build();
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xzl"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
}

最后，启动springboot工程，访问http://localhost:8080/doc.html即可

3、系列注解

3.1、@Api

@Api用于类，表示标识这个类是swagger的资源
该注解声明在controller类上，最常用的参数是tags：

tags的内容，就是生成的html文档的标题内容：

@Api注解的参数如下：

属性名	数据类型	描述
value	String	字段说明
tags	String[]	标签说明
description	String	详细描述
basePath	String	基本路径可以不配置

3.2、@ApiResponses和@ApiResponse

@ApiResponses：在Rest 接口上使用，用作返回值的描述

@ApiResponse各参数：

属性名称	数据类型	说明
code	String	响应的HTTP状态码
message	String	响应的消息内容
response	Class<?>	用于指定响应体的数据结构，
这个属性可以是实体类的 schema 定义