Knife4j使用教程（四） -- Controller类的配置注解

### Knife4j OpenAPI2 Spring Boot Starter 的配置方法 为了实现 `knife4j-openapi2-spring-boot-starter` 的集成，以下是详细的说明以及示例代码。 #### 添加依赖 首先，在项目的 `pom.xml` 文件中引入 `knife4j-openapi2-spring-boot-starter` 依赖： ```xml <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-openapi2-spring-boot-starter</artifactId> <version>3.0.3</version> <!-- 版本号可能因时间而不同，请确认最新版本 --> </dependency> ``` 此依赖会自动加载 Swagger UI 和 Knife4j 增强功能到项目中[^1]。 --- #### 配置文件设置 在 `application.yml` 或 `application.properties` 中添加必要的配置项。以下是一个典型的 YAML 配置示例： ```yaml spring: application: name: demo-service # 应用名称 swagger: base-package: com.example.demo.controller # 扫描的包路径 title: Demo API 文档 description: 这是用于演示的 API 接口文档 version: 1.0.0 license: Apache 2.0 license-url: https://www.apache.org/licenses/LICENSE-2.0.html contact: name: 开发团队 url: http://example.com email: [email protected] ``` 上述配置定义了接口文档的基础信息、扫描范围以及其他元数据。 --- #### 启用 Knife4j 功能 创建一个 Java 配置类来启用并自定义 Knife4j 的行为： ```java import springfox.documentation.swagger2.annotations.EnableSwagger2; import com.github.xiaoymin.knife4j.spring.extension.OpenApiExtensionResolver; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; @Configuration @EnableSwagger2 public class Knife4jConfig { @Bean public OpenApiExtensionResolver openApiExtensionResolver() { return new OpenApiExtensionResolver(); } } ``` 通过该配置类，Knife4j 将能够增强默认的 Swagger 功能，并提供更友好的用户体验界面。 --- #### 控制器示例 下面展示了一个简单的控制器示例，其中包含了注解以便被 Knife4j 自动识别和解析： ```java import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; @RestController @RequestMapping("/demo") @Api(tags = "Demo Controller", value = "这是一个示例模块") public class DemoController { @GetMapping("/hello") @ApiOperation(value = "获取问候语", notes = "返回一条简单的欢迎消息") public String sayHello() { return "Hello, Knife4j!"; } } ``` 以上代码片段展示了如何利用 Swagger 注解标记接口及其描述信息。 --- #### 访问 Knife4j 页面 完成上述配置后，启动应用程序并通过浏览器访问以下地址即可查看生成的 API 文档页面： ``` http://localhost:8080/doc.html ``` Knife4j 提供的功能不仅限于显示接口列表，还支持在线调试、参数校验等功能。 --- ### 注意事项 如果遇到任何异常情况（如无法正常渲染页面），可以尝试清理缓存或升级相关依赖至最新稳定版。 ---