美文网首页
21 Knife4J 接口文档

21 Knife4J 接口文档

作者: 滔滔逐浪 | 来源:发表于2023-10-17 15:34 被阅读0次

1.简介

Knife4j是一款国产开源的API接口文档在线查看工具,它基于Spring Doc 构建,提供简单的配置即可自动生成在线文档。Knife4j 不仅具备友好的界面,而且使用简单,还提供了增强功能如接口测试和Mock 数据生成,可以大大提高开发人员的工作效率。

官网定义: Knife4j 是一个集Swagger2 和OpenAPI3为一体的增强解决方案

官网地址: https://doc.xiaominfo.com(官方文档很齐全)
Knife4j界面鉴赏:https://doc.xiaominfo.com/docs/introduction/ui

2, Springboot 集成knife4j

2.1 pom.xml

添加knife4j-openapi3-spring-boot-starter依赖。

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

2.2 application.properties

注意:

  1. com.example.knife4juser要修改成您自己的包路径
  2. knife4j.enable生产环境下一定要关闭接口文档
# Swagger UI的访问路径
springdoc.swagger-ui.path=/swagger-ui.html
# 标签的排序方式
springdoc.swagger-ui.tags-sorter=alpha
# 接口的排序方式
springdoc.swagger-ui.operations-sorter=alpha
springdoc.api-docs.path=/v3/api-docs
springdoc.group-configs[0].group=default
springdoc.group-configs[0].paths-to-match=/**
# 指定需要扫描的包路径
springdoc.group-configs[0].packages-to-scan=com.example.knife4juser
# 是否启用Knife4j
knife4j.enable=true
knife4j.setting.language=zh_cn

2.3 访问

地址加/doc.html 访问文档: http://localhost:8310/doc.html

61a2bf5990a47e88d39a81eb36e37972.png

可以对接口进行在线测试


d6af4349a0420f87e468f7963447a77a.png

3 Gateway 网关聚合

如果每个微服务都按照上述配置方式(将 Knife4j 配置放在配置中心公共配置文件中),那么单独访问每个微服务接口文档会变得很麻烦。这时候可以通过网关 Gateway来聚合所有的服务的接口文档,使得我们只需要通过访问网关一次即可查看并管理整个系统的APi接口。通过这种方式,我们可以方便的统一访问和管理所有服务的接口文档,提高开发者的效率和系统可维护性。

3.1 pom.xml

Gateway 网关添加knife4j-openapi3-spring-boot-starter依赖。

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

3.2 application.properties

Gateway网关的主要配置如下:

knife4j.gateway.enabled=true:启用Knife4j的网关聚合功能。
knife4j.gateway.strategy=discover:设置Knife4j的网关扩展功能的策略为服务发现。
knife4j.gateway.discover.enabled=true:启用Knife4j的服务发现功能。
knife4j.gateway.discover.version=openapi3:设置Knife4j的服务发现功能的版本为OpenAPI 3.0。
knife4j.gateway.discover.excluded-services[0]=knife4j-gateway:设置需要排除的微服务,例如这里排除了名为knife4j-gateway的服务,不会被Knife4j的服务发现功能所发现和扩展。

spring.application.name=knife4j-gateway
server.port=10001
# 服务注册与发现
spring.cloud.nacos.discovery.username=nacos
spring.cloud.nacos.discovery.password=nacos
spring.cloud.nacos.discovery.server-addr=http://localhost:8848
# 启用了自动根据服务名建立路由
spring.cloud.gateway.discovery.locator.enabled=true
# knife4j文档
knife4j.gateway.enabled=true
knife4j.gateway.strategy=discover
knife4j.gateway.discover.enabled=true
knife4j.gateway.discover.version=openapi3
# 需要排除的微服务(eg:网关服务) 
knife4j.gateway.discover.excluded-services[0]=knife4j-gateway

3.3 访问

通过网关的地址加 /doc.html 访问文档:http://localhost:10001/doc.html

可以在这里选择切换不同的服务模块。


726eec6829e5919e4352dee7152eb464.png

3.4 设置全局参数

大多数我们请求接口都需要在请求头携带令牌等信息,可以在knif4j 设置全局参数,如下:

41ef146173a30c3bcb21c7373acea3e9.png d8213f4e06eda3b3396d8157dfe4985a.png

4 总结

本文介绍了如何在Spring Boot应用中使用Knife4j这一API文档在线查看工具,并通过配置Gateway实现了API接口聚合。

使用Knife4j可以方便地生成API接口文档,提高开发效率以及降低开发成本。而聚合接口可以使得我们可以统一管理不同服务的API文档,便于开发人员查阅和使用。


a36e6461d926875cd8c46ceb9dcad087.png

相关文章

网友评论

      本文标题:21 Knife4J 接口文档

      本文链接:https://www.haomeiwen.com/subject/qwfqidtx.html