Skip to content

Commit

Permalink
docs:更新文档
Browse files Browse the repository at this point in the history
  • Loading branch information
@xiaoymin
xiaoymin committed Jul 31, 2023
1 parent bdd05a4 commit cf51c25
Show file tree
Hide file tree
Showing 8 changed files with 135 additions and 18 deletions.
2 changes: 1 addition & 1 deletion knife4j-doc/docs/changelog/4.x/4.1.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-gateway-spring-boot-starter</artifactId>
<version>4.1.0</version>
<version>4.2.0</version>
</dependency>
```

Expand Down
89 changes: 89 additions & 0 deletions knife4j-doc/docs/changelog/4.x/4.2.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
# v4.2.0版本-2023/07/31

大家好，Knife4j v4.2.0版本发版，本次版本发版主要解决两个问题：


## 更新日志

### 依赖升级

1、升级boot3版本为3.0.7、springdoc版本‣

2、springdoc版本升级，主要包括：

- 针对Spring Boot2版本的，升级springdoc版本到1.7.0
- 针对Spring Boot3版本的，升级springdoc版本到2.1.0


### 优化`knife4j-gateway`组件

1、针对服务发现模式(`discover`)，可以动态读取服务转发路由配置前缀prefix，开发者可不用在独立配置，感谢[当幸福碰错了头](https://gitee.com/chenshifeng001)PR

2、支持除`default`默认分组外的多分组类型，感谢[谢进伟](https://gitee.com/xiejinwei)PR

3、针对在Dubbo场景下会出现聚合各个Service的场景，该版本提供自动排除服务的扩展SPI接口，开发者可集成自动扩展实现规则进行聚合服务的排除，参考[Gitee#I6YLMB](https://gitee.com/xiaoym/knife4j/issues/I6YLMB)

```javascript
@Slf4j
@Component
public class MyExcludeService implements GatewayServiceExcludeService {
@Override
public Set<String> exclude(Environment environment, Knife4jGatewayProperties properties, List<String> services) {
log.info("自定义过滤器.");
if (!CollectionUtils.isEmpty(services)){
// 排除注册中心包含order字眼的服务
return services.stream().filter(s -> s.contains("order")).collect(Collectors.toSet());
}
return new TreeSet<>();
}
}
```

4、解决在Nginx等二级代理转发情况下的路径错误问题[Gitee#gitee](https://gitee.com/xiaoym/knife4j/issues/I73AOG)、[GitHub#609](https://github.com/xiaoymin/knife4j/issues/609)、[Gitee#I6KYUJ][https://gitee.com/xiaoym/knife4j/issues/I6KYUJ]、[GitHub#603](https://github.com/xiaoymin/knife4j/issues/603)、[GitHub#586](https://github.com/xiaoymin/knife4j/issues/586)

5、增加对子服务的排序规则设置，配置如下：

```yaml
knife4j:
gateway:
tags-sorter: alpha # 接口排序规则
operations-sorter: alpha
```
不管是tag还是operation，排序规则主要提供两种实现方式：
- alpha：官方swagger-ui的默认排序规则实现。
- order：*nife4j提供的增强排序规则，开发者可在子服务中扩展x-order，根据数值来自定义排序*
6、knife4j-gateway组件增加basic验证GitHub#555
### Ui更新
1、Script脚本生成的TypeScript代码增加注释[Gitee#I6T78E](https://gitee.com/xiaoym/knife4j/issues/I6T78E)、[GitHub#568](https://github.com/xiaoymin/knife4j/issues/568)
2、OAS2新增allof特性的支持[Github#PR589](https://github.com/xiaoymin/knife4j/pull/589)
3、针对`jakarta`环境中Basic的属性提示已经match优化[GitHub#578](https://github.com/xiaoymin/knife4j/issues/578)

### 增强部分

1、openapi3规范中增加对`@ApiSupport`增强注解的支持[Gitee#I79WIJ](https://gitee.com/xiaoym/knife4j/issues/I79WIJ)

2、Post发送请求query的方式修改[Gitee#I7DNRP](https://gitee.com/xiaoym/knife4j/issues/I7DNRP)

3、优化基础jar包的引用关系，lombok、slf4j等jar包级别改为`provided`[GitHub#591](https://github.com/xiaoymin/knife4j/issues/591)


## 感谢

非常感谢以下开发者的PR贡献(排名不分先后)：

- [当幸福碰错了头](https://gitee.com/chenshifeng001)
- [谢进伟](https://gitee.com/xiejinwei)
- [最怕的、其实是孤单。。。](https://gitee.com/sky-0914)
- [fengshi20102010](https://gitee.com/fengshi20102010)
- [zskzskabcd](https://github.com/zskzskabcd)
- [小魏,小魏,我们要去哪里呀](https://github.com/galaxy-sea)
- [Pastors](https://github.com/Pastor0370)
- [King-Run](https://github.com/King-Run)
- [liuyd-cc](https://github.com/liuyd-cc)
1 change: 1 addition & 0 deletions knife4j-doc/docs/changelog/index.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ description: Knife4j发版本日志

| 新闻标题 | 发布时间 |
| ------------------------------------------------------------ | ---------- |
| [Knife4j v4.2.0 发布，优化Gateway聚合组件](changelog/x/4.2) | 2023-07-31 |
| [Knife4j v4.1.0 发布，Gateway网关聚合更上一层楼](changelog/x/4.1) | 2023-03-23 |
| [Knife4j v4.0.0 发布,新征程](https://www.oschina.net/news/222157/knife4j-4-0-released) | 2022-12-20 |
| [Knife4j 4.0计划](/docs/v4) | 2022-8-9 |
Expand Down
49 changes: 38 additions & 11 deletions ...doc/docs/middleware-sources/spring-cloud-gateway/spring-gateway-introduction.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ Maven坐标如下：
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-gateway-spring-boot-starter</artifactId>
<version>4.1.0</version>
<version>4.2.0</version>
</dependency>
```

Expand Down Expand Up @@ -65,16 +65,16 @@ knife4j:
配置属性说明：


| 配置属性名称 | 类型 | 描述 | 默认值 |
|:---------------------------------------------|---------------|-------------------------------------------------------------------------------|-----------------------------------------------------------------------------------|
| `knife4j.gateway.enabled` | boolean | 是否开启使用Gateway网关聚合组件 | `false` |
| `knife4j.gateway.strategy` | enum | 聚合的策略，主要支持两种，分别是手动配置(`manual`)、服务发现(`discover`) | `manual` |
| `knife4j.gateway.routes` | array{Router} | 通过路由注册文档 | |
| `knife4j.gateway.routes[0].name` | string | 界面显示分组名称 | `null` |
| `knife4j.gateway.routes[0].url` | string | 文档地址 | 子服务的Swagger资源接口地址(Swagger2默认/v2/api-docs,只需要配置group参数即可)，因为是从网关层走，开发者配置时别忘记了网关前缀地址。 |
| `knife4j.gateway.routes[0].service-name` | string | 访问服务名称 | `null` |
| `knife4j.gateway.routes[0].order` | int | 排序 | 0 |
| `knife4j.gateway.routes[0].context-path` | string | 路由前缀,根据实际情况自行配置 | / |
| 配置属性名称 | 类型 | 描述 | 默认值 |
| :--------------------------------------- | ------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `knife4j.gateway.enabled` | boolean | 是否开启使用Gateway网关聚合组件 | `false` |
| `knife4j.gateway.strategy` | enum | 聚合的策略，主要支持两种，分别是手动配置(`manual`)、服务发现(`discover`) | `manual` |
| `knife4j.gateway.routes` | array{Router} | 通过路由注册文档 | |
| `knife4j.gateway.routes[0].name` | string | 界面显示分组名称 | `null` |
| `knife4j.gateway.routes[0].url` | string | 文档地址 | 子服务的Swagger资源接口地址(Swagger2默认/v2/api-docs,只需要配置group参数即可)，因为是从网关层走，开发者配置时别忘记了网关前缀地址。 |
| `knife4j.gateway.routes[0].service-name` | string | 访问服务名称 | `null` |
| `knife4j.gateway.routes[0].order` | int | 排序 | 0 |
| `knife4j.gateway.routes[0].context-path` | string | 路由前缀,根据实际情况自行配置 | / |


### 服务发现模式(discover)
Expand Down Expand Up @@ -144,10 +144,37 @@ knife4j:
group-name: 订单服务名称
# 兼容OpenAPI3规范在聚合时丢失contextPath属性的异常情况，由开发者自己配置contextPath,Knife4j的前端Ui做兼容处理,与url属性独立不冲突，仅OpenAPI3规范聚合需要，OpenAPI2规范不需要设置此属性,默认为(apiPathPrefix)
context-path: /
# 该属性自4.2.0添加，支持子服务非`default`分组的其他分组聚合
# 参考 https://gitee.com/xiaoym/knife4j/pulls/87
group-names:
- 分组1
- 分组2


```

#### 排除服务

自4.2.0版本，在Spring Cloud Gateway网关聚合时，开发者可自定义排除服务的规则，实现`Knife4j`开放的接口即可
> 主要解决在Dubbo等服务的场景中聚合了不必要的服务。参考[Gitee#I6YLMB](https://gitee.com/xiaoym/knife4j/issues/I6YLMB)

```javascript
@Slf4j
@Component
public class MyExcludeService implements GatewayServiceExcludeService {
@Override
public Set<String> exclude(Environment environment, Knife4jGatewayProperties properties, List<String> services) {
log.info("自定义过滤器.");
if (!CollectionUtils.isEmpty(services)){
// 排除注册中心包含order字眼的服务
return services.stream().filter(s -> s.contains("order")).collect(Collectors.toSet());
}
return new TreeSet<>();
}
}
```

#### 场景case


Expand Down
6 changes: 3 additions & 3 deletions knife4j-doc/docs/quick-start/index.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ import IndexController3 from '!!raw-loader!./codeSamples/IndexController3.java';
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
<version>4.1.0</version>
<version>4.2.0</version>
</dependency>

```
Expand Down Expand Up @@ -128,7 +128,7 @@ Knife4j有了新的变化，主要有以下几点：
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
<version>4.1.0</version>
<version>4.2.0</version>
</dependency>
```

Expand Down Expand Up @@ -175,7 +175,7 @@ Knife4j在只有的OpenAPI3规范中，底层基础框架选择springdoc-openapi
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
<version>4.1.0</version>
<version>4.2.0</version>
</dependency>
```
Expand Down
2 changes: 1 addition & 1 deletion knife4j-doc/gitee/assets/js/4ba84b5e.7b37b182.js
View file

Large diffs are not rendered by default.

Loading

0 comments on commit cf51c25

Please sign in to comment.