You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@servicecomb.apache.org by li...@apache.org on 2024/07/08 03:20:11 UTC
(servicecomb-docs) branch master updated: improve using swagger apis (#341)
This is an automated email from the ASF dual-hosted git repository.
liubao pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/servicecomb-docs.git
The following commit(s) were added to refs/heads/master by this push:
new 2fdd856 improve using swagger apis (#341)
2fdd856 is described below
commit 2fdd8560baf8b45ab098ec4437545c55a5b3b40c
Author: liubao68 <bi...@qq.com>
AuthorDate: Mon Jul 8 11:20:06 2024 +0800
improve using swagger apis (#341)
---
.../zh_CN/docs/build-provider/springmvc.md | 194 +++++++++------------
.../docs/build-provider/swagger-annotation.md | 120 ++-----------
.../zh_CN/docs/spring-boot/diff-spring-mvc.md | 10 +-
java-chassis-reference/zh_CN/mkdocs.yml | 2 +-
4 files changed, 106 insertions(+), 220 deletions(-)
diff --git a/java-chassis-reference/zh_CN/docs/build-provider/springmvc.md b/java-chassis-reference/zh_CN/docs/build-provider/springmvc.md
index 2534fd0..e6e7d62 100644
--- a/java-chassis-reference/zh_CN/docs/build-provider/springmvc.md
+++ b/java-chassis-reference/zh_CN/docs/build-provider/springmvc.md
@@ -1,12 +1,7 @@
# 用 Spring MVC 开发微服务
Spring MVC 是 spring-web 项目定义的一套注解，开发者可以使用这套注解定义 REST 接口。 servicecomb 也
-支持使用这套标签定义 REST 接口。需要注意的是，servicecomb 只是使用这些注解，而注解的实现是项目自行开发的，
-实现的功能集合是 Spring MVC 注解的子集。可以阅读文章后面的内容了解具体的标签集合和使用约束。
-
-[SpringMVC Sample][spring-mvc-sample] 提供了一些基础的代码示例，可以下载使用。
-
-[spring-mvc-sample]: https://github.com/apache/servicecomb-samples/tree/master/java-chassis-samples/springmvc-sample
+支持使用这套标签定义 REST 接口。需要注意的是，servicecomb 只是使用这些注解，而注解的实现是项目自行开发的， 实现的功能集合是 Spring MVC 注解的子集。
## 开发步骤
@@ -14,139 +9,108 @@ Spring MVC 是 spring-web 项目定义的一套注解，开发者可以使用这
* 定义服务接口（可选）
- 定义接口是一个好习惯， 它不是必须的。
+定义接口是一个好习惯， 它不是必须的。
- ```java
- public interface Hello {
- String sayHi(String name);
- String sayHello(Person person);
- }
- ```
+```java
+@RequestMapping(path = "/provider")
+public interface ProviderService {
+ @GetMapping("/sayHello")
+ String sayHello(@RequestParam("name") String name);
+}
+```
* 实现服务接口
- 在服务的实现类上打上注解 `@RestSchema`，指定 `schemaId`。 注意 `schemaId` 需要保证微服务范围内唯一。
-
- ```java
- @RestSchema(schemaId = "springmvcHello")
- @RequestMapping(path = "/springmvchello", produces = MediaType.APPLICATION_JSON)
- public class SpringmvcHelloImpl implements Hello {
- @Override
- @RequestMapping(path = "/sayhi", method = RequestMethod.POST)
- public String sayHi(@RequestParam(name = "name") String name) {
- return "Hello " + name;
- }
-
- @Override
- @RequestMapping(path = "/sayhello", method = RequestMethod.POST)
- public String sayHello(@RequestBody Person person) {
- return "Hello person " + person.getName();
- }
- }
- ```
-
-
-## ServiceComb支持的 Spring MVC 注解说明
-
-servicecomb 支持使用 Spring MVC 提供的注解 `org.springframework.web.bind.annotation` 来声
-明REST接口，但是两者是独立的实现，而且有不一样的设计目标。servicecomb 的目标是提供跨语言、支持多通信协议的
-框架，因此去掉了Spring MVC中一些对跨语言支持不是很好的特性，也不支持特定运行框架强相关的特性，比
-如直接访问Servlet协议定义的`HttpServletRequest`。servicecomb 没有实现`@Controller`相关功
-能, 只实现了`@RestController`，即通过MVC模式进行页面渲染等功能都是不支持的。
-
-下面是一些具体差异。
+在服务的实现类上打上注解 `@RestSchema`，指定 `schemaId`。 注意 `schemaId` 需要保证微服务范围内唯一。
+
+```java
+@RestSchema(schemaId = "ProviderController",
+ schemaInterface = ProviderService.class)
+public class ProviderController implements ProviderService {
+ @Override
+ public String sayHello(String name) {
+ return "Hello " + name;
+ }
+}
+```
+
+
+## Java Chassis 支持的 Spring MVC 注解说明
* 常用标签支持
- 下面是CSE对于Spring MVC常用标签的支持情况。
-
- ***表1-1 Spring MVC注解情况说明***
-
-| 标签名称 | 是否支持 | 说明 |
-|------------------|:----:|:------------------------------------------------------------|
-| RequestMapping | 是 | 不允许制定多个Path，一个接口只允许一个Path，必须显示的声明 method 属性，只能定义唯一一个 method |
-| GetMapping | 是 | |
-| PutMapping | 是 | |
-| PostMapping | 是 | |
-| DeleteMapping | 是 | |
-| PatchMapping | 是 | |
-| RequestParam | 是 | 注意含义与Spring MVC不同。Java Chassis 表示 query 参数。 |
-| CookieValue | 是 | |
-| PathVariable | 是 | |
-| RequestHeader | 是 | |
-| RequestBody | 是 | 目前支持application/json，plain/text |
-| RequestPart | 是 | 用于文件上传的场景，对应的标签还有Part、MultipartFile |
-| ResponseBody | 否 | 返回值缺省都是在body返回 |
-| ResponseStatus | 否 | 可以通过ApiResponse指定返回的错误码 |
-| RequestAttribute | 是 | 注意含义与Spring MVC不同。Java Chassis 表示 form 参数。 |
-| SessionAttribute | 否 | Servlet协议相关的标签 |
-| MatrixVariable | 否 | |
-| ModelAttribute | 否 | |
-| ControllerAdvice | 否 | |
-| CrossOrigin | 否 | |
-| ExceptionHandler | 否 | |
-| InitBinder | 否 | |
+下面是CSE对于Spring MVC常用标签的支持情况。
+
+***表1-1 Spring MVC注解情况说明***
+
+| 标签名称 | 是否支持 | 说明 |
+|:------------------|:-----|:------------------------------------------------------------|
+| RequestMapping | 是 | 不允许制定多个Path，一个接口只允许一个Path，必须显示的声明 method 属性，只能定义唯一一个 method |
+| GetMapping | 是 | |
+| PutMapping | 是 | |
+| PostMapping | 是 | |
+| DeleteMapping | 是 | |
+| PatchMapping | 是 | |
+| RequestParam | 是 | 注意含义与Spring MVC不同。Java Chassis 表示 query 参数。 |
+| CookieValue | 是 | |
+| PathVariable | 是 | |
+| RequestHeader | 是 | |
+| RequestBody | 是 | 目前支持application/json，plain/text |
+| RequestPart | 是 | 用于文件上传的场景，对应的标签还有Part、MultipartFile |
+| ResponseBody | 否 | 返回值缺省都是在body返回 |
+| ResponseStatus | 否 | 可以通过ApiResponse指定返回的错误码 |
+| RequestAttribute | 是 | 注意含义与Spring MVC不同。Java Chassis 表示 form 参数。 |
+| SessionAttribute | 否 | Servlet协议相关的标签 |
+| MatrixVariable | 否 | |
+| ModelAttribute | 否 | |
+| ControllerAdvice | 否 | |
+| CrossOrigin | 否 | |
+| ExceptionHandler | 否 | |
+| InitBinder | 否 | |
+
* 服务声明方式
- Spring MVC使用`@RestController`声明服务，而ServiceComb使用`@RestSchema`声明服务，并且需
+Spring MVC使用`@RestController`声明服务，而ServiceComb使用`@RestSchema`声明服务，并且需
要显式地使用`@RequestMapping`声明服务路径，以区分该服务是采用Spring MVC的标签还是使用JAX RS的标签。
- ```
- @RestSchema(schemaId = "springmvcHello")
- @RequestMapping(path = "/springmvchello", produces = MediaType.APPLICATION_JSON)
- public class SpringmvcHelloImpl implements Hello {
- ......
- }
- ```
+```java
+@RestSchema(schemaId = "springmvcHello")
+@RequestMapping(path = "/springmvchello", produces = MediaType.APPLICATION_JSON)
+public class SpringmvcHelloImpl implements Hello {
+ // implementations
+}
+```
- servicecomb 也支持 `@RestController` 声明，等价于 `@RestSchma(schemaId="服务的class名称")`，这个
- 功能可以简化用户将老的应用改造为 servicecomb 。 建议用户使用`@RestSchema`显式声明schemaId，在管理
- 接口基本的配置项的时候，更加直观。
+Java Chassis 也支持 `@RestController` 声明，等价于 `@RestSchma(schemaId="服务的class名称")`，这个功能可以简化用户将老的应用改造为Java Chassis。 建议用户使用`@RestSchema`显式声明schemaId，在管理接口基本的配置项的时候，更加直观。
- **注意**：如果不希望Java-Chassis扫描`@RestController`注解作为REST接口类处理，需要增加配置
- `servicecomb.provider.rest.scanRestController=false` 以关闭此功能。
+**注意**：如果不希望Java-Chassis扫描`@RestController`注解作为REST接口类处理，需要增加配置
+`servicecomb.provider.rest.scanRestController=false` 以关闭此功能。
* 数据类型支持
- Spring 技术实现的 Spring MVC，可以在服务定义中使用多种数据类型，只要这种数据类型能够被json序列化和
- 反序列化。比如：
-
- ```
- // 抽象类型
- public void postData(@RequestBody Object data)
- // 接口定义
- public void postData(@RequestBody IPerson interfaceData)
- // 没指定类型的泛型
- public void postData(@RequestBody Map rawData)
- ```
-
- Spring 技术早期都是基于 JSP/Servlet 协议标准的，还可以使用相关的 context 参数，比如：
-
- ```
- // 具体协议相关的类型
- public void postData(HttpServletRequest rquest, HttpServletResponse response)
- ```
-
- servicecomb 对于数据类型存在一定的限制，不允许使用接口、抽象类等数据类型定义参数，虽然 servicecomb
- 支持使用 Object 这个特殊的类型来处理类型无法确定的情况，但是建议尽可能少使用，使用 Object 作为类型，
- 运行时的类型不确定，可能给客户端代码的书写带来一定麻烦。
-
- servicecomb 也支持一些 context 参数， 参考[使用 Context 参数](context-param.md) 。但是由于 servicecomb 默认的运行环境并不是 JSP/Servlet 协议
- 环境，因此不能直接使用 `HttpServletRequest` 和 `HttpServletResponse`。
+采用Spring Web MVC，可以在服务定义中使用多种数据类型，只要这种数据类型能够被Json序列化和反序列化。比如：
- ServiceComb在数据类型的支持方面的更多说明，请参考： [接口定义和数据类型](interface-constraints.md)
+```
+// 抽象类型
+public void postData(@RequestBody Object data)
+// 接口定义
+public void postData(@RequestBody IPerson interfaceData)
+// 没指定类型的泛型
+public void postData(@RequestBody Map rawData)
+// 具体协议相关的类型
+public void postData(HttpServletRequest rquest)
+```
-* 其他
+这些使用方式，无法确定接口的详细 RestFul 语义和输入输出格式，Java Chassis强调一个核心的原则：接口的输入输出在接口定义的时候就已经确定好，并且可以通过生成的 Open API 来显示的表达。因此不建议在接口声明的时候，采用接口、泛型、抽象类型等。
- 更多开发过程中碰到的问题，可以参考[案例](https://bbs.huaweicloud.com/blogs/8b8d8584e70d11e8bd5a7ca23e93a891)。开发过程中存在疑问，也可以在这里进行提问。
+Java Chassis 也支持一些 context 参数， 参考[使用 Context 参数](context-param.md) 。但是由于 servicecomb 默认的运行环境并不是 JSP/Servlet 协议 环境，因此不能直接使用 `HttpServletRequest` 和 `HttpServletResponse`。
+Java Chassis 在数据类型的支持方面的更多说明，请参考： [接口定义和数据类型](interface-constraints.md)
## 在响应中包含 HTTP header
-可以有多种方式在响应中包含 HTTP header， 下面代码展示了使用 ResponseEntity 包含 HTTP header。 需要注意
-使用 @ResponseHeaders 声明返回的 header 信息。 包含了 @ResponseHeaders 以后， 接口生成的契约中，也可以
-看到对应的 header 参数。
+可以有多种方式在响应中包含 HTTP header， 下面代码展示了使用 ResponseEntity 包含 HTTP header。 需要注意使用 @ResponseHeaders 声明返回的 header 信息。 包含了 @ResponseHeaders 以后， 接口生成的契约中，也可以看到对应的 header 参数。
```java
@ResponseHeaders({@ResponseHeader(name = "h1", response = String.class),
diff --git a/java-chassis-reference/zh_CN/docs/build-provider/swagger-annotation.md b/java-chassis-reference/zh_CN/docs/build-provider/swagger-annotation.md
index e8b9165..c750fd6 100644
--- a/java-chassis-reference/zh_CN/docs/build-provider/swagger-annotation.md
+++ b/java-chassis-reference/zh_CN/docs/build-provider/swagger-annotation.md
@@ -1,109 +1,27 @@
# 使用 Swagger 注解
-采用 Spring MVC 或者 JAX RS 注解已经能够描述大部分常用的契约信息，但是仍然不足以描述所有契约信息。可以混合
-使用 Swagger 注解，进一步补充契约信息，使得契约信息更加完整。当 Spring MVC 或者 JAR RS 注解描述的信息与
-Swagger 注解描述的信息重复时，以 Swagger 注解描述的信息为准，即 Swagger 注解具有更高的优先级。
+采用 Spring MVC 或者 JAX RS 注解已经能够描述RestFul/RPC运行时需要的契约信息，但是仍然不足以描述所有契约信息，比如描述、扩展等。可以混合使用 Swagger 注解，进一步补充契约信息，使得契约信息更加完整。当 Spring MVC 或者 JAR RS 注解描述的信息与 Swagger 注解描述的信息重复时，以 Swagger 注解描述的信息为准，即 Swagger 注解具有更高的优先级。
-关于Swagger注解的含义，可以在[Swagger注解文档](swagger-annotation)中找到官方说明。可以对
-照该官方文档与本说明来了解如何在ServiceComb框架下使用注解指定Swagger契约的各项属性。
+关于Swagger注解的含义，可以在 [Swagger注解文档](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations) 中找到官方说明。
-[swagger-annotation]: https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X
+## 例子
-## `@Api`
+* @OpenAPIDefinition
-> `@Api`作用于类级别，在Swagger官方描述中是用于将一个Class标注为一个Swagger资源。但该注解
-> 在ServiceComb中不是必须的，ServiceComb可以根据`@RestSchema`和`@RpcSchema`确定需要从哪些
-> 类中解析出Swagger契约。
+```java
+@OpenAPIDefinition(servers = {@Server(url = "/SameService1")})
+public interface SameService1 {
+ @GetMapping(path = "/sayHello")
+ String sayHello(@RequestParam("name") String name);
+}
+```
-| 属性 | 类型 | 说明 |
-| :--- | :------ | :--- |
-| tags | string | 设置当前Class下定义的operation的默认tag值 |
-| consumes | string | 指定契约级别的请求体数据格式，可以使用逗号分隔指定多个 |
-| produces | string | 指定契约级别的响应体数据格式，可以使用逗号分隔指定多个 |
+* @Operation
-## `@SwaggerDefinition`
-
-> 作用于类级别，用于定义一个Swagger资源中的信息。
-
-| 属性 | 类型 | 说明 |
-| :--- | :------ | :--- |
-| info.title | string | 契约文件标题 |
-| info.description | string | 描述信息 |
-| info.version | string | 契约版本号 |
-| info.termsOfService | string | 服务条款 |
-| info.contact | string | 联系信息，包含name、email、url属性 |
-| info.license | string | 许可证信息，包含name、url属性 |
-| info.extensions | string | 扩展信息 |
-| consumes | string | 接收的请求格式 |
-| produces | string | 返回的应答格式 |
-| schemes | SwaggerDefinition.Scheme | 可选值有`HTTP/HTTPS/WS/WSS/DEFAULT` |
-| tags | `@Tag` | Tag定义，@Tag包含name、description、externalDocs三个属性 |
-| externalDocs | `@externalDocs` | 外部说明文档链接，包含value、url两个属性 |
-
-## `@ApiOperation`
-
-> 作用于方法级别，用于描述一个Swagger operation。
-
-| 属性 | 类型 | 说明 |
-| :--- | :------ | :--- |
-| value | string | 方法的简要说明，对应于Swagger契约operation的`summary`字段 |
-| notes | string | 详细信息，对应于Swagger契约operation的`description`字段 |
-| tags | string | 标注operation的标签 |
-| code | int | 响应消息的HTTP状态码 |
-| response | Class<?> | 方法返回值类型 |
-| responseContainer | string | 包装返回值的容器类型，可选值为`List`、`Set`、`Map` |
-| responseHeaders | `@ResponseHeader` | 响应消息的HTTP头，ServiceComb支持的属性值为`name`、`response`、`responseContainer` |
-| consumes | string | 指定请求体的数据格式 |
-| produces | string | 指定响应体的数据格式 |
-| protocols | string | 设置可用的协议（schemes），可选值有`http`、`https`、`ws`、`wss`，逗号分隔 |
-| httpMethod | string | 设置HTTP方法 |
-| hidden | boolean | 是否隐藏此方法 |
-
-## `@ApiImplicitParam`
-
-> 作用于方法级别，用于说明Swagger文档中operation的参数的属性。
->
-> **注意**：ServiceComb可以根据代码和SpringMVC、JAX-RS的注解自动推断出参数名称。如果`@ApiImplicitParam`配置的参数名称与自动推断的参数名不同，则则该注解配置的参数将被作为一个新的参数加入到注解所在的operation中；否则将覆盖同名参数的属性。
-
-| 属性 | 类型 | 说明 |
-| :--- | :------ | :--- |
-| name | string | 参数名称 |
-| value | string | 参数说明 |
-| required | boolean | 是否是必填参数 |
-| dataType | string | 参数数据类型 |
-| paramType | string | 参数位置，有效的可选值为path/query/body/header/form |
-| allowableValues | string | 参数的有效值范围 |
-| allowEmptyValue | boolean | 是否允许空值 |
-| allowMultiple | boolean | 是否允许多个值（若为true，则可以将参数作为数组） |
-| collectionFormat | string | 以何种格式指定参数数组，当前ServiceComb支持的值为`csv/multi` |
-| defaultValue | string | 参数默认值 |
-| example | string | 一个非body参数的示例值 |
-| format | string | 允许用户自定义数据格式，详情参见Swagger官方文档 |
-
-## `@ApiImplicitParams`
-
-> `@ApiImplicitParams`作用于方法、类级别，用于批量指定多个`@ApiImplicitParam`。
-
-| 属性 | 类型 | 说明 |
-| :--- | :------ | :--- |
-| value | `@ApiImplicitParam` | 参数定义 |
-
-## `@ApiResponse`
-
-> 用于描述返回消息的HTTP状态码所表达的含义。通常`@ApiOperation`可以表示一个正常情况返回消息的HTTP状态码，其他情形下的HTTP状态码由本注解描述。根据Swagger官方文档的描述，本注解不应该直接用于方法级别，而应该被包含在`@ApiResponses`中。
-
-| 属性 | 类型 | 说明 |
-| :--- | :------ | :--- |
-| code | int | 返回消息的HTTP状态码 |
-| message | string | 返回值的说明信息 |
-| response | Class<?> | 返回值的类型 |
-| responseContainer | string | 返回值的包装容器，可选值为`List/Set/Map` |
-| responseHeaders | @ResponseHeader | 描述一组返回消息的HTTP头，ServiceComb支持的`@ResponseHeader`的属性有`name`、`description`、`response`、`responseContainer` |
-
-## `@ApiResponses`
-
-> 作用于方法、类级别，用于指定和说明一组返回值。
-
-| 属性 | 类型 | 说明 |
-| :--- | :------ | :--- |
-| value | `@ApiResponse` | 返回消息说明 |
+```java
+@GetMapping(path = "/specialNameModel")
+@Operation(summary = "specialNameModel", operationId = "specialNameModel")
+public SpecialNameModel specialNameModel(@RequestParam("code") int code, @RequestBody SpecialNameModel model) {
+ return model;
+}
+```
diff --git a/java-chassis-reference/zh_CN/docs/spring-boot/diff-spring-mvc.md b/java-chassis-reference/zh_CN/docs/spring-boot/diff-spring-mvc.md
index 8003510..ee524e8 100644
--- a/java-chassis-reference/zh_CN/docs/spring-boot/diff-spring-mvc.md
+++ b/java-chassis-reference/zh_CN/docs/spring-boot/diff-spring-mvc.md
@@ -1,10 +1,14 @@
# 与Spring Web MVC开发习惯的差异
-Java Chassis支持使用Spring MVC提供的标签\(org.springframework.web.bind.annotation\)来声明REST接口，但是两者是独立的实现，并且有不一样的设计目标。Java Chassis的目标是提供跨语言、支持多通信协议的框架，因此去掉了Spring Web MVC中一些对跨语言支持不是很好的特性，也不支持特定运行框架强相关的特性，比如直接访问Servlet协议定义的HttpServletRequest。Java Chassis支持的Spring Web MVC标签是Spring Boot的子集， 下面是一些显著的差别。
+Java Chassis支持使用Spring MVC提供的标签 `org.springframework.web.bind.annotation` 来声明REST接口，但是两者是独立的实现，并且有不一样的设计目标。Java Chassis的目标是提供跨语言、支持多通信协议的RESTFul/RPC框架，可以运行于J2EE/JavaEE容器或者普通的HTTP服务器，不依赖于J2EE/JavaEE。而Spring MVC诞生比较早，很多功能都会依赖于J2EE/JavaEE。 Java Chassis整体的应用架构采用后端和前端分离的微服务架构，不会在单独的微服务实现中使用MVC模式。
+
+相对于Spring MVC， Java Chassis去掉了一些对跨语言支持不是很好的特性，也不支持特定运行框架强相关的特性，比如直接访问 `Servlet` 定义的HttpServletRequest、HttpServletResponse，或者使用HttpAttribute、HttpSession进行会话管理等，也不支持MVC模式一些相关的内容，比如ModelAndView等。
+
+Java Chassis支持的Spring Web MVC标签是Spring Boot的子集， 下面是一些显著的差别。
* 服务声明方式
-Spring MVC使用@RestController声明服务，而Java Chassis使用@RestSchema声明服务，并且需要显示的使用@RequestMapping声明服务路径，以区分该服务是采用Spring Web MVC的标签还是使用JAX RS的标签。
+Spring MVC使用 `@RestController` 声明服务，而Java Chassis使用 `@RestSchema` 声明服务，并且需要显示的使用 `@RequestMapping` 声明服务路径，以区分该服务是采用Spring Web MVC的标签还是使用JAX RS的标签。
```
@RestSchema(schemaId = "hello")
@@ -28,7 +32,7 @@ public void postData(@RequestBody Map rawData)
public void postData(HttpServletRequest rquest)
```
-Java Chassis不支持上诉类型。因为Java Chassis会根据接口定义生成契约，从上面的接口定义，如果不结合实际的实现代码或者额外的开发文档说明，无法直接生成契约。
+这些使用方式，无法确定接口的详细 RestFul 语义和输入输出格式，Java Chassis强调一个核心的原则：接口的输入输出在接口定义的时候就已经确定好，并且可以通过生成的 Open API 来显示的表达。因此不建议在接口声明的时候，采用接口、泛型、抽象类型等。
>>> 说明： 为了支持快速开发，Java Chassis的数据类型限制也在不停的扩充，比如支持HttpServletRequest，但是实际在使用的时候，他们与WEB服务器的语义是不一样的，比如不能直接操作流。因此建议开发者在的使用场景下，尽可能使用契约能够描述的类型，让代码阅读性更好。此外，Spring针对DispatcherServlet做了大量的扩展，这些扩展对于Java Chassis是不适用的。
diff --git a/java-chassis-reference/zh_CN/mkdocs.yml b/java-chassis-reference/zh_CN/mkdocs.yml
index 0d2b152..6483eb8 100644
--- a/java-chassis-reference/zh_CN/mkdocs.yml
+++ b/java-chassis-reference/zh_CN/mkdocs.yml
@@ -21,11 +21,11 @@ nav:
- 用JAX-RS开发微服务: build-provider/jaxrs.md
- 用SpringMVC开发微服务: build-provider/springmvc.md
- 用透明RPC开发微服务: build-provider/transparent-rpc.md
+ - 使用Swagger注解: build-provider/swagger-annotation.md
- 只发布interface的方法为服务接口: build-provider/use-interface.md
- 异步处理: build-provider/reactive.md
- 使用 Context 参数: build-provider/context-param.md
- 多个返回值和错误码: build-provider/multi-code.md
- - 使用Swagger注解: build-provider/swagger-annotation.md
- 接口定义和数据类型: build-provider/interface-constraints.md
- 服务监听地址和发布地址: build-provider/listen-address-and-publish-address.md
- 线程池: build-provider/thread-pool.md