API文档生成工具-----Knife4j的详细介绍、配置及应用

一、Knife4j是什么?

Knife4j是一个基于Swagger构建的开源Java API文档工具，它为Java开发者提供了生成、展示和调试API文档的功能。它提供了一套美观且功能强大的界面，可以自动生成API文档，并支持接口分组、参数设置、请求示例、响应模型配置等高级功能。
Knife4j的特点包括：
1.界面友好：Knife4j提供了一个漂亮、直观的界面，使得API文档易于阅读和理解。
2.自动生成文档：通过集成Swagger，Knife4j可以自动从代码中解析API注解，生成规范的API文档。
3.接口分组：可以根据业务需求将接口进行分组，方便用户对接口进行组织和查看。
4.参数设置：支持多种参数类型的展示和设置，包括基本类型、对象、集合等。
5.请求示例：可以显示接口请求示例，并提供调试接口的功能，方便用户进行调试和测试。
6.响应模型配置：提供全局统一的响应模型配置，方便用户对接口返回数据进行管理和定义。
使用Knife4j可以帮助开发人员快速生成并展示API文档，方便团队协作和接口开发。同时，Knife4j也提供了丰富的配置选项和样式定制功能，使得用户可以根据自己的需求进行个性化定制。

二、Knife4j如何配置?

1.添加依赖:
在pom.xml中添加Knife4j的依赖项。代码如下：

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

2.配置Knife4j
如果需要自定义Knife4j的配置，可以自己创建一个配置类，来指定文档的访问路径、标题、版本等信息。
以下是一个手动配置 Knife4j 的示例：

/*** Knife4j配置类*/
@Configuration
@EnableKnife4j
public class Knife4jConfiguration {/*** 【重要】指定Controller包路径*/private String basePackage = "xx.xx.xx";/*** 主机名*/private String host = "http://abc.cn";/*** 标题*/private String title = "xx商城后台管理平台在线API文档";/*** 简介*/private String description = "xx商城后台管理平台在线API文档";/*** 服务条款URL*/private String termsOfServiceUrl = "http://www.apache.org/licenses/LICENSE-2.0";/*** 联系人*/private String contactName = "Java教学部";/*** 联系网址*/private String contactUrl = "http://java.aa.cn";/*** 联系邮箱*/private String contactEmail = "xx@yy.cn";/*** 版本号*/private String version = "1.0";/*** OpenApiExtensionResolver 是Knife4j中的一个扩展点，用于解析并加载自定义的OpenAPI扩展信息。*/@Autowiredprivate OpenApiExtensionResolver openApiExtensionResolver;/*** 创建并配置 Docket 对象，用于 Swagger 文档的生成和展示** @return 配置好的 Docket 对象*/@Beanpublic Docket docket() {// 定义分组名称String groupName = "1.0.0";// 创建并配置 Docket 对象Docket docket = new Docket(DocumentationType.SWAGGER_2).host(host) // 设置主机名.apiInfo(apiInfo()) // 设置 API 文档信息.groupName(groupName) // 设置分组名称.select().apis(RequestHandlerSelectors.basePackage(basePackage)) // 设置扫描的 Controller 包路径.paths(PathSelectors.any()) // 设置 API 路径匹配规则.build().extensions(openApiExtensionResolver.buildExtensions(groupName)); // 构建扩展信息return docket;}/*** 创建并配置 ApiInfo 对象，用于设置 Swagger 文档的基本信息** @return 配置好的 ApiInfo 对象*/private ApiInfo apiInfo() {return new ApiInfoBuilder().title(title) // 设置标题.description(description) // 设置简介.termsOfServiceUrl(termsOfServiceUrl) // 设置服务条款 URL.contact(new Contact(contactName, contactUrl, contactEmail)) // 设置联系信息.version(version) // 设置版本号.build();}
}

注意:对应参数需要换成自己的！！！

三、在Controller类或方法上如何使用?

在你的Controller类或方法上使用Knife4j提供的注解来生成API文档。常用的注解包括：
@Api：作用于Controller类上，用于标识该类为一个API文档的控制器。
@ApiOperation：作用于Controller类中的方法上，用于描述API接口的功能和作用。
@ApiImplicitParam：作用于Controller类中的方法参数上，用于描述方法参数的详细信息。
@ApiParam：作用于Controller类中的方法参数上，用于描述方法参数的详细信息。
以下是一个使用Knife4j注解的示例：

@RestController  
@RequestMapping("/api")
@Api(tags  = "示例API") 
public class ExampleController {@ApiOperation("获取用户信息")@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path")@GetMapping("/users/{id}")public User getUser(@PathVariable Long id) {// ...}
}

四、如何访问API文档?

1.启动你的Spring Boot应用程序。
2.确保项目启动成功之后，在浏览器中通过以下网址来访问API文档:

http://localhost:端口号/doc.html

其他项目应用

<!--java生成接口文档-->
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><knife4j.version>2.0.7</knife4j.version>
</dependency>

import com.fasterxml.classmate.TypeResolver;
import com.yuntongxun.aihelper.api.dto.QualityContent;
import com.yuntongxun.aihelper.api.dto.condition.TriggerConditionDTO;
import com.yuntongxun.aihelper.api.entry.mq.RecognizeMessage;
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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;/*** @author * @Description* @Date 创建于 2021/6/21 10:49 上午*/
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {@Bean(value = "Api2")public Docket defaultApi2(TypeResolver typeResolver) {return new Docket(DocumentationType.SWAGGER_2).apiInfo(new ApiInfoBuilder()//.title("swagger-bootstrap-ui-demo RESTful APIs").description("# aihelper APIs").termsOfServiceUrl("http://www.yuntongxun.com/").version("5.0").build())//分组名称.groupName("5.0版本").select()//这里指定Controller扫描包路径.apis(RequestHandlerSelectors.basePackage("com.yuntongxun.aihelper.api.controller")).paths(PathSelectors.any()).build().additionalModels(typeResolver.resolve(QualityContent.SensitiveWordsContent.class)).additionalModels(typeResolver.resolve(QualityContent.RegexContent.class)).additionalModels(typeResolver.resolve(QualityContent.FlowContent.class)).additionalModels(typeResolver.resolve(QualityContent.SpeechSpeedContent.class)).additionalModels(typeResolver.resolve(QualityContent.MuteContent.class)).additionalModels(typeResolver.resolve(QualityContent.SentimentContent.class)).additionalModels(typeResolver.resolve(QualityContent.InterposeContent.class)).additionalModels(typeResolver.resolve(TriggerConditionDTO.class)).additionalModels(typeResolver.resolve(RecognizeMessage.class));}
}

参考 ：链接