打造优美易用的API文档：Spring Cloud集成Knife4j指南

🏅 欢迎点赞 👍 收藏 ⭐留言 📝 如有错误敬请指正！

Spring Cloud是基于Spring Boot的微服务框架，而Knife4j是Swagger的增强版，它能够为SpringBoot的Web应用程序生成在线API文档。在本文中，我将介绍如何在SpringCloud项目中集成Knife4j，以生成美观且易于使用的API文档。

1. 添加Knife4j依赖

首先，我们需要在Spring Cloud项目中添加Knife4j的依赖。打开pom.xml文件，并在标签中添加以下代码：

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

这个依赖包含了Knife4j的核心库和Spring Boot的自动配置模块，它能够帮助我们轻松地集成Knife4j。

2. 配置Swagger

接下来，我们需要配置Swagger，以便Knife4j能够正确地读取我们的API文档。打开application.yml文件，并添加以下代码：

spring:
  swagger:
    enabled: true
    title: "My API"
    description: "My API Description"
    version: "1.0.0"
    contact:
      name: "My Contact Name"
      url: "https://www.example.com/contact"
      email: "contact@example.com"

这个配置文件告诉Spring Boot启用Swagger，并设置API的标题、描述和版本号。还可以设置联系人的名称、网址和电子邮件地址。

3. 创建API文档

接下来，我们需要创建API文档。打开一个控制器类，并在类上方添加以下注释：

@Api(tags = "示例控制器")
@RestController
@RequestMapping("/example")
public class ExampleController {
    // ...
}

这个注释告诉Knife4j这是一个控制器，并将其标记为“示例控制器”。你可以为每个控制器创建一个不同的标签，以便在文档中对它们进行分类。

接下来，在每个API方法上方添加以下注释：

@ApiOperation(value = "示例API", notes = "这是一个示例API")
@GetMapping("/api")
public String exampleApi() {
    return "Hello, world!";
}

这个注释告诉Knife4j这是一个API方法，并设置API的标题和说明。

4. 访问API文档

现在，我们已经准备好访问我们的API文档了。启动Spring Cloud应用程序，并在Web浏览器中打开以下网址：

http://localhost:8080/doc.html

这将打开Knife4j的Swagger UI，它能够自动读取我们的API文档，并以易于理解的方式呈现它们。你可以使用Swagger UI来测试API，并查看每个API的详细信息。

5. 高级配置

除了上面的基本配置外，Knife4j还提供了一些高级配置选项，可以帮助我们进一步自定义API文档。以下是一些可用的高级配置选项：

5.1. 修改UI界面

默认情况下，Knife4j使用Swagger UI作为UI界面，但是它也提供了其他UI界面的选项。如果你想使用其他UI界面，可以在pom.xml文件中添加相应的依赖，并在application.yml文件中设置knife4j.ui.type属性。例如，如果你想使用ReDoc UI，可以将knife4j-ui-reDoc作为依赖，并设置knife4j.ui.type为"reDoc"。

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-ui-reDoc</artifactId>
    <version>3.0.1</version>
</dependency>

knife4j:
  ui:
    type: "reDoc"

5.2. 配置API分组

如果你有多个控制器，并希望将它们分组显示在API文档中，可以使用@ApiGroup注释。例如，如果你有一个名为"User"的控制器和一个名为"Order"的控制器，可以将它们分组为"user"和"order"。在application.yml文件中添加以下代码：

knife4j:
  groups:
    user:
      name: "用户管理"
      packages: "com.example.user"
      description: "用户相关的API"
    order:
      name: "订单管理"
      packages: "com.example.order"
      description: "订单相关的API"

这个配置将在文档中创建两个分组，一个名为"用户管理"，另一个名为"订单管理"，并将相应的控制器放置在每个分组中。

5.3. 设置全局响应消息

在API文档中，每个API都有一组预定义的响应消息。如果你想在全局范围内定义自己的响应消息，可以使用@GlobalResponseMessage注释。例如，如果你想将所有API的成功响应消息设置为"操作成功"，可以添加以下注释：

@GlobalResponseMessage(
    status = {
        @GlobalResponseMessage.GlobalResponse(
            responseCode = "200",
            description = "操作成功"
        )
    }
)

这个注释将在所有API中设置成功响应消息为"操作成功"。

总结

在本文中，我们学习了如何在Spring Cloud项目中集成Knife4j，并创建美观且易于使用的API文档。我们介绍了基本的配置选项以及一些高级配置选项，以帮助我们自定义API文档。通过使用Knife4j，我们可以轻松地为我们的API创建在线文档，并使其易于使用和理解。