Knife4j 生成 API 文档

Knife4j 是一个基于 Swagger 的增强解决方案，它为 Java 开发者提供了一个更美观、更强大的 API 文档工具。Knife4j 继承了 Swagger 的特性，并且在此基础上进行了优化和增强，使得生成的 API 文档更加符合国内开发者的使用习惯。

Knife4j 的主要特点

1. 界面优化：Knife4j 提供了更加现代和美观的界面设计，使得 API 文档更加易读和易用。
2. 功能增强：除了基本的 API 文档展示，Knife4j 还提供了诸如离线文档、接口排序、访问控制等增强功能。
3. 扩展性：Knife4j 支持自定义扩展，可以根据项目需求进行个性化配置。
4. 兼容性：Knife4j 兼容 Swagger 2.x 和 OpenAPI 3.0，可以无缝集成到现有的 Swagger 项目中。

使用 Knife4j 生成接口文档的步骤

1. 添加依赖：在 Maven 或 Gradle 项目中添加 Knife4j 的依赖。

   Maven 依赖示例：

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

   Gradle 依赖示例：

   implementation 'com.github.xiaoymin:knife4j-spring-boot-starter:2.0.9'
   

2. 配置 Swagger：在 Spring Boot 项目中配置 Swagger，启用 Knife4j。

   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;
   import springfox.documentation.swagger2.annotations.EnableSwagger2;
   
   @Configuration
   @EnableSwagger2
   public class SwaggerConfig {
   
       @Bean
       public Docket createRestApi() {
           return new Docket(DocumentationType.SWAGGER_2)
                   .apiInfo(apiInfo())
                   .select()
                   .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                   .paths(PathSelectors.any())
                   .build();
       }
   
       private ApiInfo apiInfo() {
           return new ApiInfoBuilder()
                   .title("API文档")
                   .description("API文档描述")
                   .version("1.0.0")
                   .build();
       }
   }
   

3. 使用注解：在 Controller 和 Model 类中使用 Swagger 提供的注解来描述 API 接口和数据模型。

   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("/api")
   @Api(tags = "示例接口")
   public class ExampleController {
   
       @GetMapping("/hello")
       @ApiOperation("示例接口")
       public String hello() {
           return "Hello, World!";
       }
   }
   

4. 访问文档：启动 Spring Boot 应用后，可以通过浏览器访问 http://localhost:8080/doc.html 来查看生成的 API 文档。

通过以上步骤，你可以使用 Knife4j 快速生成美观且功能强大的 API 文档，提升开发和调试效率。

在 Java 中使用 Swagger 或 Knife4j 生成 API 文档时，注解是非常重要的工具，它们用于描述 API 接口、参数、响应等信息。以下是一些常用的 Swagger 注解及其用法：

@Api

@Api 注解用于标记一个类，表示这个类是一个 API 接口的控制器。它可以设置一些全局属性，如标签、描述等。

@RestController
@RequestMapping("/api")
@Api(tags = "示例接口", description = "这是一个示例接口的描述")
public class ExampleController {
    // 接口方法
}

@ApiOperation

@ApiOperation 注解用于标记一个方法，表示这个方法是 API 接口的一个操作。它可以设置操作的名称、描述、响应类型等。

@GetMapping("/hello")
@ApiOperation(value = "示例接口", notes = "这是一个示例接口的详细描述", response = String.class)
public String hello() {
    return "Hello, World!";
}

@ApiParam

@ApiParam 注解用于标记方法参数，表示这个参数的名称、描述、是否必须等信息。

@PostMapping("/create")
@ApiOperation("创建资源")
public ResponseEntity<Resource> createResource(
    @ApiParam(value = "资源对象", required = true) @RequestBody Resource resource) {
    // 处理创建资源的逻辑
}

@ApiModel

@ApiModel 注解用于标记一个类，表示这个类是一个数据模型。它可以设置模型的名称和描述。

@ApiModel(value = "资源对象", description = "表示一个资源的详细信息")
public class Resource {
    // 属性
}

@ApiModelProperty

@ApiModelProperty 注解用于标记一个类的属性，表示这个属性的名称、描述、是否必须等信息。

@ApiModel(value = "资源对象", description = "表示一个资源的详细信息")
public class Resource {
    @ApiModelProperty(value = "资源ID", required = true)
    private Long id;

    @ApiModelProperty(value = "资源名称", required = true)
    private String name;

    // Getter 和 Setter 方法
}

@ApiResponse

@ApiResponse 注解用于标记一个方法的响应，表示这个方法的响应状态码、描述等信息。

@GetMapping("/hello")
@ApiOperation(value = "示例接口", notes = "这是一个示例接口的详细描述")
@ApiResponse(code = 200, message = "请求成功")
public String hello() {
    return "Hello, World!";
}

@ApiResponses

@ApiResponses 注解用于标记一个方法的多个响应，可以包含多个 @ApiResponse 注解。

@GetMapping("/hello")
@ApiOperation(value = "示例接口", notes = "这是一个示例接口的详细描述")
@ApiResponses(value = {
    @ApiResponse(code = 200, message = "请求成功"),
    @ApiResponse(code = 404, message = "资源未找到")
})
public String hello() {
    return "Hello, World!";
}

通过合理使用这些注解，可以生成详细且易于理解的 API 文档，帮助开发者更好地理解和使用 API 接口。