以前接口文档都是直接用丝袜哥的,最近几年一直用大佬的这个:Knife4j
,尤其是到4.0.0版本以后,已经非常好用了。支持Swagger2规范
和OpenAPI3规范
,同时也有Spring Boot 2.x
和Spring Boot 3.x
的区分,还是很全面的,尤其Spring Boot 3.x
版本,基本不用什么配置,方便。在微服务方案中,Knife4j
更给出了gateway网关聚合版本。用起来真的很爽。
先看 官方文档
本次使用版本如下:
- Spring Cloud Alibaba:2023.0.1.2
- Spring Boot:3.3.3
- Knife4j:4.4.0
- Jdk:17
1. 微服务模块
基本就是照搬的官网例子,不用改什么。除非有特别需要配置的,我感觉一般这个就够了。
1.1 pom.xml
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- Knife4j -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
</dependency>
<!-- nacos包 -->
<dependency>
<groupId>com.alibaba.cloud</groupId>
<artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
</dependency>
<dependency>
<groupId>com.alibaba.cloud</groupId>
<artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
</dependency>
1.2 application.yml
spring:
application:
name: oauth2-server
# springdoc-openapi项目配置
springdoc:
swagger-ui:
path: /swagger-ui.html
tags-sorter: alpha
operations-sorter: alpha
api-docs:
path: /v3/api-docs
group-configs:
- group: 'default'
paths-to-match: '/**'
packages-to-scan: com.example.test.oauth2.controller
# knife4j的增强配置,不需要增强可以不配
knife4j:
enable: true
setting:
language: zh_cn
1.3 文档
该微服务模块可以直接看接口文档的:http://ip:port/doc.html
2. Gateway网关模块
这个配置有 手动 和 自动发现 2种模式。看哪种适合需要
2.1 pom.xml
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-gateway</artifactId>
</dependency>
<!-- Knife4j-gateway -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-gateway-spring-boot-starter</artifactId>
</dependency>
<!-- nacos包 -->
<dependency>
<groupId>com.alibaba.cloud</groupId>
<artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
</dependency>
<dependency>
<groupId>com.alibaba.cloud</groupId>
<artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
</dependency>
<!-- Spring Cloud Gateway 的早期版本中,Ribbon 被用作默认的负载均衡器, Spring Cloud 2020.0.0 版本开始,Ribbon 被废弃,Spring Cloud LoadBalancer 成为了推荐的负载均衡方案。为了灵活性,需要手动引入,不然请求到不了各个服务-->
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-loadbalancer</artifactId>
</dependency>
<!-- 做资源服务器权限校验用的,没用别引入 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>
2.2 application.yml
spring:
application:
name: gateway-server
cloud:
gateway:
discovery:
locator:
# 为true时会自动生成路由规则,我们手动配置,值设置false
enabled: false
lowerCaseServiceId: true
routes:
# 自定义路由 ID
- id: oauth2-route
# 采用 LoadBalanceClient 方式请求,以 lb:// 开头,后面的是注册在 Nacos 上的服务名
uri: lb://oauth2-server
# Predicate 断言,主要作用是匹配用户的请求路径,有很多种用法
predicates:
# 路径匹配,一般是指要走网关时要写的路径地址
- Path=/gateway/oauth2/**
filters:
# 指路由到其他服务时去掉path中几层路径,如值为1,则去掉1层,即去掉/gateway
- StripPrefix=1
- id: resource-route
uri: lb://resource-server
predicates:
- Path=/gateway/resource/**
filters:
- StripPrefix=1
knife4j:
gateway:
# 是否开启
enabled: true
# 排序规则(tag/operation排序自4.2.0版本新增)
# 取值:alpha-默认排序规则,官方swagger-ui默认实现,order-Knife4j提供的增强排序规则,开发者可扩展x-order,根据数值来自定义排序
tags-sorter: order
operations-sorter: order
# 指定服务发现的模式聚合微服务文档,并且是默认`default`分组
# 这是手动模式的,需要指定url,注意 url 和 context-path 这2个值的填写
# strategy: manual
# routes:
# - name: 认证服务
# # 真实通过网关访问子服务接口文档的uri地址:
# # /v3/api-docs?group=default是固定值,
# # /oauth2 是微服务的 context-path
# # /gateway 是我在网关路由断言中自定义添加的,可以是/api等其他的,如果没有,这一层可以不用
# url: /gateway/oauth2/v3/api-docs?group=default
# service-name: oauth2-server
# # 路由前缀
# # 这个值在V3版本中,界面中调试时添加到微服务中uri前面的,一般和上面url前面部分相同
# context-path: /gateway/oauth2
# order: 1
# 自动发现模式,读取nacos注册中心里的微服务
strategy: discover
discover:
enabled: true
# 指定版本号(Swagger2|OpenAPI3)
version : openapi3
# 需要排除的微服务(eg:网关服务)
excluded-services:
- gateway-server
# 各个聚合服务的个性化配置,key:注册中心中的服务名称,value:个性化配置
service-config:
oauth2-server:
# 排序
order: 1
# 前端显示名称
group-name : 认证服务
# 重新指定basePath,一般在OpenAPI3规范中需要
context-path: /
resource-server:
# 排序
order: 2
# 前端显示名称
group-name : 资源服务
# 重新指定basePath,一般在OpenAPI3规范中需要
context-path: /
2.3 网关接口文档
注意:
- openApi3 注解 和 swagger2不一样:参考官网
swagger2 | swagger3 | 注解位置 |
---|---|---|
@Api | @Tag | Controller类 |
@ApiOperation(value = "foo", notes = "bar") | @Operation(summary = "foo", description = "bar") | api端口方法 |
@ApiImplicitParams | @Parameters | api端口方法 |
@ApiImplicitParam | @Parameter | api方法的参数 |
@ApiParam | @Parameter | api方法的参数 |
@ApiIgnore | @Parameter(hidden = true) 或 @Operation(hidden = true) 或 @Hidden | 各处皆可 |
@ApiModel | @Schema | DTO类 |
@ApiModelProperty | @Schema(description = "注释",requiredMode = RequiredMode.REQUIRED) | DTO属性 |
@ApiModelProperty(hidden = true) | @Schema(accessMode = READ_ONLY) | DTO属性 |
@ApiResponse(code = 404, message = "foo") | @ApiResponse(responseCode = "404", description = "foo") | api端口方法 |
- 如果接口请求参数是实体类对象,可以添加
@RequestBody
(json格式)或者@ParameterObject
(表单格式),使页面显示正常。