刀锋下的困境——springboot3.0.11-SNAPSHOT集成knife4j-openapi3踩坑全记录

后端

2023-02-05 02:01:43

Knife4j-OpenAPI3：开启流畅的在线API文档之旅

困扰：无法访问API文档的无奈

当我们满怀期待地打开Swagger UI，却发现doc.html无法访问，那种失落感可想而知。别担心，Knife4j-OpenAPI3来了，它将帮助你轻松解决这个难题！

Knife4j-OpenAPI3的强大救星

Knife4j-OpenAPI3是一款功能强大的API文档生成工具，它基于OpenAPI 3.0标准，能够快速生成美观、易用的在线API文档。

解锁doc.html访问的简单步骤

使用Knife4j-OpenAPI3，只需要几个简单的步骤，即可轻松开启doc.html之门：

引入依赖

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

配置application.yml

knife4j:
  basic:
    enable: true
    doc:
      title: 项目API文档
      description: 项目API文档详细
      version: 1.0

启动项目

java -jar 项目启动jar包

解决图标缺失的妙招

如果发现图标缺失，也不要着急，我们有解决办法：

手动添加图标
在resources/static目录下创建knife4j-webjar目录，然后将图标文件knife4j.css和knife4j.svg复制到该目录下。
配置knife4j.yaml
在resources目录下创建knife4j.yaml文件，并添加以下内容：

knife4j:
  static-resource-enabled: false

重启项目
重新启动项目，图标即可显示。

从零开始应用Knife4j-OpenAPI3

现在，让我们从零开始体验Knife4j-OpenAPI3的魅力吧！

创建项目
使用SpringBoot创建项目，并引入knife4j-openapi3依赖。
配置Swagger注解
在Controller方法上添加swagger注解，例如：

@ApiOperation(value = "用户登录", notes = "根据用户名和密码登录")
@PostMapping("/login")
public Result login(@RequestParam String username, @RequestParam String password) {
    return Result.success("登录成功！");
}

启动项目

java -jar 项目启动jar包

访问文档
在浏览器地址栏输入http://localhost:端口号/doc.html即可访问在线API文档。

Knife4j-OpenAPI3的魅力

Knife4j-OpenAPI3不只是一个文档生成器，它还提供了诸多实用功能：

支持多版本文档生成
支持服务发现
支持安全认证
支持自定义文档主题

常见问题解答

如何解决doc.html无法访问的问题？
答：使用Knife4j-OpenAPI3，并按照本文提供的步骤操作即可。
为什么图标无法显示？
答：请检查是否手动添加了图标，或者配置了knife4j.yaml文件。
如何使用Knife4j-OpenAPI3生成多版本文档？
答：在项目中添加不同的swagger配置，并分别配置apiVersion和apiInfo。
如何配置Knife4j-OpenAPI3的服务发现？
答：在application.yml文件中配置knife4j.discovery参数。
如何自定义Knife4j-OpenAPI3的文档主题？
答：使用knife4j.ui配置项，可以自定义文档的主题和样式。