knife4j-openapi2集成

### 集成 Knife4j 与 OpenAPI2

在 Spring Boot 项目中集成 Knife4j 和 OpenAPI2 可以为 API 提供强大的文档生成功能以及交互式的 API 测试界面。以下是详细的集成过程：

#### 添加依赖项

为了使 Spring Boot 应用程序支持 Knife4j 和 OpenAPI2，需修改 `pom.xml` 文件并加入必要的 Maven 依赖。

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

<!-- 如果使用的是 Swagger 2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

#### 启用 Swagger 支持

创建配置类来启用 Swagger 并自定义其行为。

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot 中文 API 文档")
                .description("更多请关注 http://www.knife4j.com")
                .termsOfServiceUrl("http://www.knife4j.com")
                .contact(new Contact("xiaoymin", "", ""))
                .version("1.0")
                .build();
    }
}

此段代码通过构建 `Docket` 对象指定了要扫描的基础包路径，并设置了 API 的基本信息[^1]。

#### 使用注解标记控制器方法

为了让生成的文档更加清晰易懂，建议为每个 RESTful 接口添加相应的元数据注释。

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("/example")
@Api(tags = {"示例模块"})
public class ExampleController {

    @ApiOperation(value="获取字符串", notes="返回固定的'hello world'")
    @GetMapping("/hello")
    public String helloWorld(){
        return "Hello, World!";
    }
}

上述例子展示了如何利用 `@Api`, `@ApiOperation` 注解给定标签和操作描述，从而让开发者更容易理解各个端点的功能[^3]。

---