Knife4j的基本使用

eqa11

已于 2025-01-08 14:43:52 修改

阅读量994

点赞数 11

CC 4.0 BY-SA版权

文章标签： java spring boot

于 2024-09-09 08:38:15 首次发布

本文链接：https://blog.csdn.net/NiNg_1_234/article/details/142041645

文章目录

Knife4j的基本使用

Knife4j的基本使用

一、引言

在微服务架构和前后端分离开发模式下，API文档的编写和维护变得尤为重要。Knife4j是一款基于Swagger2和OpenAPI3的API文档生成工具，它不仅能够自动生成API文档，还提供了丰富的UI界面和增强功能，使得API文档的展示更加直观和美观。本文将详细介绍Knife4j的基本使用方法，帮助开发者快速上手并生成高质量的API文档。

二、环境准备与依赖引入

1、创建Spring Boot项目

首先，需要创建一个Spring Boot项目。可以使用Spring Initializr快速生成项目结构。

2、引入Knife4j依赖

在项目的pom.xml文件中引入Knife4j的依赖包。根据Spring Boot的版本选择合适的Knife4j版本。以下是一个适用于Spring Boot 2.x版本的依赖示例：

<!-- 引入Knife4j的官方start包 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
    <version>4.4.0</version>
</dependency>

三、配置Knife4j

1、创建配置类

在项目中创建一个配置类，用于配置Knife4j的相关参数。以下是一个简单的配置类示例：

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {

    @Bean(value = "dockerBean")
    public Docket dockerBean() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        .description("# Knife4j RESTful APIs")
                        .termsOfServiceUrl("https://doc.xiaominfo.com/")
                        .contact("xiaoymin@foxmail.com")
                        .version("1.0")
                        .build())
                .groupName("用户服务")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
}

2、配置文件中的设置

在application.properties或application.yml文件中，可以开启Knife4j的增强模式：

knife4j.enable=true

四、使用示例

1、创建Controller类

在项目中创建一个Controller类，并使用Swagger注解来描述API接口：

@Api(tags = "首页模块")
@RestController
public class IndexController {

    @ApiImplicitParam(name = "name", value = "姓名", required = true)
    @ApiOperation(value = "向客人问好")
    @GetMapping("/sayHi")
    public ResponseEntity<String> sayHi(@RequestParam(value = "name") String name) {
        return ResponseEntity.ok("Hi: " + name);
    }
}

2、访问API文档

启动Spring Boot项目后，打开浏览器，访问以下地址即可查看生成的API文档：

http://localhost:8080/doc.html

3、查看

在Knife4j中查看接口的请求和响应数据可以通过以下步骤进行：

查看请求数据

启动项目并访问文档页面：
启动Spring Boot项目后，打开浏览器，访问Knife4j的文档页面，通常地址为 http://localhost:8080/doc.html。
定位到具体接口：
在文档页面中，找到需要查看的接口。接口会按照控制器类或分组进行展示。
查看请求参数：
点击具体接口后，会展示该接口的详细信息，包括请求方法（如GET、POST）、请求路径、请求参数等。请求参数会详细列出每个参数的名称、类型、是否必填等信息。

查看响应数据

查看响应示例：
在接口的详细信息中，通常会有一个“响应示例”部分，这里会展示接口的响应数据格式。如果接口返回的是JSON格式的数据，这里会展示JSON结构。
在线调试查看实时响应：
Knife4j提供了在线调试功能。在接口的详细信息页面，可以输入请求参数，点击“Try it out”按钮，即可发送请求并查看实时的响应数据。这包括响应状态码、响应头、响应体等详细信息。

通过这些步骤，开发者可以在Knife4j中方便地查看和测试接口的请求和响应数据，从而更好地进行接口开发和调试.