快速入手SpringBoot+Knife4

• SpringBoot
• Knife4j

1.需要新创建一个 SrpingBoot 项目

• Spring Initializr创建（Idea专业版）

• 或者 创建Maven项目，添加依赖，改造成SpringBoot项目。

===> 需要在pom文件中加入

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

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
<dependencies>

<build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <version>2.6.13</version>
            </plugin>
        </plugins>
</build>

===> src\main\ resources下新建一个文件，命名application.yml
===>新建启动类,这里是项目启动入口，注意新建该类的位置。

2.引入Knife4j

Knife4j官网
官网文档中，一些常见的Spring Boot版本及其对应的Knife4j版本兼容推荐：

Spring Boot版本	Knife4j Swagger2规范	Knife4j OpenAPI3规范
1.5.x~2.0.0	<Knife4j 2.0.0	>=Knife4j 4.0.0
2.0~2.2	Knife4j 2.0.0 ~ 2.0.6	>=Knife4j 4.0.0
2.2.x~2.4.0	Knife4j 2.0.6 ~ 2.0.9	>=Knife4j 4.0.0
2.4.0~2.7.x	>=Knife4j 4.0.0	>=Knife4j 4.0.0
>= 3.0	>=Knife4j 4.0.0	>=Knife4j 4.0.0

按照自己SpringBoot项目版本选择引入的Knife4j版本,并且，大版本不同，Maven的依赖坐标不同。可以参照官方文档引入。
本文示例，使用SpringBoot 2.6.13版本，Knife4j 4.0.0版本、Swagger2规范
pom文件需要引入的坐标是

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

在application.yml中开启Knife4j

knife4j:
  enable: true

Knife4j应用于Api，也就是SpringBoot的contoller层

• 新建controller,添加方法、注解
  
  在浏览器输入localhost:9090/doc.html 就可以访问发送请求。（本文所用的端口是9090，默认是8080）
  

以下是一些常用的 Knife4j 注解以及它们的示例用法：

1. @Api：用于描述 Controller 类的基本信息，包括名称、描述等。

   @Api(value = "用户管理", tags = "用户相关接口")
   @RestController
   @RequestMapping("/user")
   public class UserController {
       // ...
   }
   

2. @ApiOperation：用于描述 Controller 方法的基本信息，包括名称、描述等。

   @ApiOperation(value = "获取用户信息", notes = "根据用户 ID 获取用户详细信息")
   @GetMapping("/{userId}")
   public User getUser(@PathVariable Long userId) {
       // ...
   }
   

3. @ApiImplicitParams 和 @ApiImplicitParam：用于描述方法参数的详细信息，包括参数名、数据类型、描述等。

   @ApiOperation(value = "添加用户", notes = "添加新用户")
   @ApiImplicitParams({
       @ApiImplicitParam(name = "user", value = "用户信息", dataType = "User"),
       @ApiImplicitParam(name = "accessToken", value = "访问令牌", dataType = "String", paramType = "header")
   })
   @PostMapping("/add")
   public User addUser(@RequestBody User user, @RequestHeader String accessToken) {
       // ...
   }
   

4. @ApiResponse：用于描述方法的响应信息，包括响应状态码和响应模型。

   @ApiOperation(value = "更新用户信息", notes = "根据用户 ID 更新用户信息")
   @ApiResponse(code = 200, message = "更新成功", response = User.class)
   @ApiResponse(code = 400, message = "请求参数错误")
   @PutMapping("/update/{userId}")
   public ResponseEntity<User> updateUser(@PathVariable Long userId, @RequestBody User user) {
       // ...
   }
   

5. @ApiResponses：用于描述方法的多个响应情况。

   @ApiOperation(value = "删除用户", notes = "根据用户 ID 删除用户")
   @ApiResponses({
       @ApiResponse(code = 200, message = "删除成功"),
       @ApiResponse(code = 404, message = "用户不存在")
   })
   @DeleteMapping("/delete/{userId}")
   public ResponseEntity<String> deleteUser(@PathVariable Long userId) {
       // ...
   }