博客

一、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扩展信息。
     */
    @Autowired
    private OpenApiExtensionResolver openApiExtensionResolver;

    /**
 	* 创建并配置 Docket 对象，用于 Swagger 文档的生成和展示
 	*
	* @return 配置好的 Docket 对象
 	*/
	@Bean
	public 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

注意：端口号要改成自己的！！！