knife4j-openapi3使用

### 如何使用 Knife4j OpenAPI3 进行接口文档生成和管理

#### 配置 Maven 依赖
为了使 Spring Boot 应用程序能够支持 OpenAPI3 和 Knife4j，需在 `pom.xml` 文件中引入必要的依赖项[^1]。

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

<!-- springdoc-openapi-ui 提供了对 OpenAPI 3 的支持 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.14</version>
</dependency>

#### 启动类配置
确保启动类上添加了 `@EnableKnife4j` 注解以便开启 Knife4j 功能。此操作允许应用程序利用 Knife4j 扩展特性来增强 API 文档界面[^2]。

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@EnableKnife4j
@SpringBootApplication
public class Application {
    
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

#### 使用注释定义 API 接口
通过应用标准 JAX-RS 或者 Spring MVC 注释以及特定于 Swagger/OpenAPI 的元数据标签（如 `@Operation`, `@Parameter`），可以在代码级别精确控制所暴露 RESTful 资源的行为及其对应的文档描述[^3]。

@RestController
@RequestMapping("/example")
@Api(tags = "示例模块")
public class ExampleController {

    @GetMapping("/{id}")
    @Operation(summary = "获取单个资源", description = "根据ID查询指定记录")
    public ResponseEntity<?> get(@PathVariable("id") Long id){
        // 实现逻辑...
    }

    @PostMapping("/")
    @Operation(summary = "创建新实体", responses = {
            @ApiResponse(responseCode = "201", description = "成功"),
            @ApiResponse(responseCode = "400", description = "请求参数错误")
    })
    public ResponseEntity<Void> create(@Valid @RequestBody Entity entity){
        // 创建业务处理...
    }
}

完成上述设置之后，在浏览器中访问 URL `http://localhost:8080/doc.html#/home` 即可查看由 Knife4j 自动生成并渲染后的交互式 API 文档页面。