You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@dubbo.apache.org by li...@apache.org on 2021/01/30 11:28:38 UTC
[dubbo-spi-extensions] 26/39: 修改说明文档
This is an automated email from the ASF dual-hosted git repository.
liujun pushed a commit to branch 2.7.x
in repository https://gitbox.apache.org/repos/asf/dubbo-spi-extensions.git
commit 4d371e9a4ef1e8709061f19e737502f45574decc
Author: qq213539 <21...@qq.com>
AuthorDate: Tue Dec 22 15:22:31 2020 +0800
修改说明文档
---
dubbo-api-docs/README.md | 54 +++++++++++++++++++++++++++++++--------------
dubbo-api-docs/README_ch.md | 43 ++++++++++++++++++++++--------------
2 files changed, 64 insertions(+), 33 deletions(-)
diff --git a/dubbo-api-docs/README.md b/dubbo-api-docs/README.md
index 3ed8aed..baebc8d 100644
--- a/dubbo-api-docs/README.md
+++ b/dubbo-api-docs/README.md
@@ -6,12 +6,27 @@ Dubbo api documents, test tools, generate documents according to annotations, an
Adding some annotations can generate a swagger like document without turning a non web Dubbo project into a web project
+## Involving repositorys
+* [dubbo-spi-extensions](https://github.com/apache/dubbo-spi-extensions)
+ [\branch: 2.7.x\dubbo-api-docs](https://github.com/apache/dubbo-spi-extensions/tree/2.7.x/dubbo-api-docs):
+ Dubbo-Api-Docs related annotation ,annotation parsing
+* [dubbo-admin](https://github.com/KeRan213539/dubbo-admin): Dubbo-Api-Docs document display, test function
+
## How to use?
+
1. Dubbo api docs annotation added to method parameters of Dubbo project
- * Dubbo provider project introduces dubbo-api-docs-core
- * If Dubbo's interface and parameters are a separate jar package project, introduce dubbo-api-docs-annotations
+ * Dubbo provider project introduces dubbo-api-docs-core
+ * If Dubbo's interface and parameters are a separate jar package project, introduce dubbo-api-docs-annotations
+ * Add the annotation @EnableDubboApiDocs to the project startup class (marked with @SpringBootApplication)
+ or configuration class (marked with @Configuration) of the provider project to enable the Dubbo API Docs
+ * In order to avoid increasing the resource consumption in the production environment, it is recommended
+ to create a configuration class to enable Dubbo API Docs, and use it with the @Profile("dev") annotation
+ * Of course, Dubbo API Docs consumed a little CPU resources when the project starting and used a little
+ memory for caching. In the future, it will consider putting the contents of the cache into the metadata
+ center
### Current Version: Same as Dubbo version
+
```
<dependency>
<groupId>org.apache.dubbo</groupId>
@@ -25,7 +40,9 @@ Adding some annotations can generate a swagger like document without turning a n
<version>${dubbo-version}</version>
</dependency>
```
-2. Download [dubbo-admin](https://github.com/apache/dubbo-admin) [Download](https://github.com/apache/dubbo-admin/releases)
+
+2.
+Download [dubbo-admin](https://github.com/apache/dubbo-admin) [Download](https://github.com/apache/dubbo-admin/releases)
3. Start dubbo-admin
@@ -34,16 +51,18 @@ Adding some annotations can generate a swagger like document without turning a n
5. Enter the "API Doc" module
### Annotation use
-* @ApiModule class annotation: dubbo API module information, used to mark the purpose of an interface class module
+
+* @EnableDubboApiDocs: 配制注解, 启用 dubbo api docs 功能
+* @ApiModule: class annotation, dubbo API module information, used to mark the purpose of an interface class module
* value: module name
* apiInterface: Provider implemented interface
* version: module version
-* @ApiDoc method annotation: dubbo API information, used to mark the purpose of an dubbo API
+* @ApiDoc: method annotation, dubbo API information, used to mark the purpose of an dubbo API
* value: API name
* description: API description(HTML tags available)
* version: API version
* responseClassDescription: response class description
-* @RequestParam class property/method Parameter annotation: mark request parameters
+* @RequestParam: class property/method Parameter annotation, mark request parameters
* value: parameter name
* required: true/false required parameter
* description: parameter description
@@ -51,33 +70,34 @@ Adding some annotations can generate a swagger like document without turning a n
* defaultValue: parameter default value
* allowableValues: Allowed values. After setting this property, a drop-down list will be generated for the parameter
* Note: a drop-down selection box will be generated after using this property
- * Parameters of boolean type do not need to be set with this property. A drop-down list of true / false will be generated by default
- * Parameters of enumeration type will automatically generate a drop-down list. If you do not want to open all enumeration values, you can set this property separately.
-* @ResponseProperty Class attribute annotation: mark response parameters
+ * Parameters of boolean type do not need to be set with this property. A drop-down list of true / false will be
+ generated by default
+ * Parameters of enumeration type will automatically generate a drop-down list. If you do not want to open all
+ enumeration values, you can set this property separately.
+* @ResponseProperty: Class attribute annotation, mark response parameters
* value: parameter name
* example: example
### Use note
+
* Get API list direct connection:
+
> Because Dubbo services with different functions may be registered in the same registration center,
-> but the name of the interface used by Dubbo doc is the same, so the interface of Dubbo doc uses direct
-connection to obtain the list of different interfaces of different functions.
+> but the name of the interface used by Dubbo doc is the same, so the interface of Dubbo doc uses direct connection to obtain the list of different interfaces of different functions.
> The test can be connected directly or through the registration center
* The response bean (the return type of the interface) supports custom generics, but only one generic placeholder.
-* About the use of Map: the key of map can only use the basic data type. If the key of map is not the basic data type, the generated key is not in the standard JSON format, and an exception will occur
+* About the use of Map: the key of map can only use the basic data type. If the key of map is not the basic data type,
+ the generated key is not in the standard JSON format, and an exception will occur
* The API's synchronous / asynchronous is from org.apache.dubbo.config.annotation.Service.async
## Project structure
+
* dubbo-api-docs-annotations: Document generation annotation project
* dubbo-api-docs-core: Responsible for annotation analysis and document information acquisition interface (Dubbo API)
* dubbo-api-docs-examples: Use example
* readmeImgs: Pictures used by README.md
-## Major dependent version
-* spring-boot: 2.3.4.RELEASE
-* dubbo: apache dubbo 2.7.8
-* icework in front(iceworks 4.0)
-
## Screenshot
+
diff --git a/dubbo-api-docs/README_ch.md b/dubbo-api-docs/README_ch.md
index 89c231d..4633a4d 100644
--- a/dubbo-api-docs/README_ch.md
+++ b/dubbo-api-docs/README_ch.md
@@ -6,11 +6,22 @@ dubbo 接口文档、测试工具,根据注解生成文档,并提供测试功能
增加一些注解就能生成类似swagger的文档, 不会把非web的dubbo项目变为web项目.
+## 相关项目
+* [dubbo-spi-extensions](https://github.com/apache/dubbo-spi-extensions)
+ [\分支: 2.7.x\dubbo-api-docs](https://github.com/apache/dubbo-spi-extensions/tree/2.7.x/dubbo-api-docs):
+ Dubbo-Api-Docs 相关注解,解析注解
+* [dubbo-admin](https://github.com/KeRan213539/dubbo-admin): Dubbo-Api-Docs 文档展示,测试功能
+
## 如何使用?
-1. dubbo项目的方法参数中加上 dubbo api docs注解
- * dubbo提供者项目引入 dubbo-api-docs-core
- * 如果dubbo的接口和参数是一个单独的jar包项目,引入dubbo-api-docs-annotations
-
+
+1. dubbo项目的方法参数中加上 dubbo api docs 注解
+ * dubbo提供者项目引入 dubbo-api-docs-core
+ * 如果dubbo的接口和参数是一个单独的jar包项目,引入dubbo-api-docs-annotations
+ * 在提供者项目的项目启动类(标注了@SpringBootApplication的类)或者配制类(标注了@Configuration的类)中增加注解
+ @EnableDubboApiDocs 以启用Dubbo Api Docs功能
+ * 为避免增加生产环境中的资源占用, 建议单独创建一个配制类用于启用Dubbo Api Docs, 并配合 @Profile("dev") 注解使用
+ * 当然, Dubbo Api Docs 仅在项目启动时多消耗了点CPU资源, 并使用了一点点内存用于缓存, 将来会考虑将缓存中的内容放到元数据中心.
+
### 当前版本: 同Dubbo版本号
```
@@ -36,16 +47,18 @@ dubbo 接口文档、测试工具,根据注解生成文档,并提供测试功能
5. 进入"接口文档"模块
### 注解使用
-* @ApiModule 类注解: dubbo接口模块信息,用于标注一个接口类模块的用途
+
+* @EnableDubboApiDocs: 配制注解, 启用 dubbo api docs 功能
+* @ApiModule: 类注解, dubbo接口模块信息,用于标注一个接口类模块的用途
* value: 模块名称
* apiInterface: 提供者实现的接口
* version: 模块版本
-* @ApiDoc 方法注解: dubbo 接口信息,用于标注一个接口的用途
+* @ApiDoc: 方法注解, dubbo 接口信息,用于标注一个接口的用途
* value: 接口名称
* description: 接口描述(可使用html标签)
* version: 接口版本
* responseClassDescription: 响应的数据的描述
-* @RequestParam 类属性/方法参数注解:标注请求参数
+* @RequestParam: 类属性/方法参数注解,标注请求参数
* value: 参数名
* required: 是否必传参数
* description: 参数描述
@@ -55,31 +68,29 @@ dubbo 接口文档、测试工具,根据注解生成文档,并提供测试功能
* 注:使用该属性后将生成下拉选择框
* boolean 类型的参数不用设置该属性,将默认生成 true/false 的下拉列表
* 枚举类型的参数会自动生成下拉列表,如果不想开放全部的枚举值,可以单独设置此属性.
-* @ResponseProperty 类属性注解: 标注响应参数
+* @ResponseProperty: 类属性注解, 标注响应参数
* value: 参数名
* example: 示例
-
+
### 使用注意
+
* 获取接口列表直连:
+
> 由于可能不同功能的dubbo服务都会注册到同一个注册中心,但是dubbo doc
> 使用的接口名是一样的,所以dubbo doc的接口采用直连方式以获取到不同功能服务的不同接口列表
> 测试可以直连或者走注册中心
* 响应bean(接口的返回类型)支持自定义泛型, 但只支持一个泛型占位符
-* 关于Map的使用:Map的key只能用基本数据类型.如果Map的key不是基础数据类型,生成的
-就不是标准json格式,会出异常
+* 关于Map的使用:Map的key只能用基本数据类型.如果Map的key不是基础数据类型,生成的 就不是标准json格式,会出异常
* 接口的同步/异步取自 org.apache.dubbo.config.annotation.Service.async
## 项目结构
+
* dubbo-api-docs-annotations: 文档生成辅助注解项目
* dubbo-api-docs-core: 负责注解解析,文档信息获取接口(dubbo接口)
* dubbo-api-docs-examples: 使用示例
* readmeImgs: README.md 用到的图片
-## 主要依赖版本
-* spring-boot: 2.3.4.RELEASE
-* dubbo: apache dubbo 2.7.8
-* 前端使用飞冰(iceworks 4.0)
-
## 页面截图
+
\ No newline at end of file