You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@dubbo.apache.org by il...@apache.org on 2020/12/22 06:51:59 UTC
[dubbo-website] branch master updated: 增加 dubbo-api-docs 文档 (#684)
This is an automated email from the ASF dual-hosted git repository.
iluo pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/dubbo-website.git
The following commit(s) were added to refs/heads/master by this push:
new b720829 增加 dubbo-api-docs 文档 (#684)
b720829 is described below
commit b720829dc4b72f7cc4b3343aa549cb31cd33fe4d
Author: 邪影oO <21...@qq.com>
AuthorDate: Tue Dec 22 14:51:53 2020 +0800
增加 dubbo-api-docs 文档 (#684)
---
content/en/docs/v2.7/admin/ops/apidocs.md | 108 ++++++++++++++++++++++++++++++
content/zh/docs/v2.7/admin/ops/apidocs.md | 101 ++++++++++++++++++++++++++++
static/imgs/admin/dubbo_docs_en.png | Bin 0 -> 600733 bytes
static/imgs/admin/dubbo_docs_zh.png | Bin 0 -> 538526 bytes
4 files changed, 209 insertions(+)
diff --git a/content/en/docs/v2.7/admin/ops/apidocs.md b/content/en/docs/v2.7/admin/ops/apidocs.md
new file mode 100644
index 0000000..e4c92c4
--- /dev/null
+++ b/content/en/docs/v2.7/admin/ops/apidocs.md
@@ -0,0 +1,108 @@
+---
+type: docs
+title: "API Docs&Test"
+linkTitle: "API Docs&Test"
+weight: 4
+---
+
+## dubbo api docs
+
+Dubbo api documents, test tools, generate documents according to annotations, and provide test functions
+
+Adding some annotations can generate a swagger like document without turning a non web Dubbo project into a web project
+
+## 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
+ * 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>
+ <artifactId>dubbo-api-docs-annotations</artifactId>
+ <version>${dubbo-version}</version>
+</dependency>
+
+<dependency>
+ <groupId>org.apache.dubbo</groupId>
+ <artifactId>dubbo-api-docs-core</artifactId>
+ <version>${dubbo-version}</version>
+</dependency>
+```
+
+2.
+Download [dubbo-admin](https://github.com/apache/dubbo-admin) [Download](https://github.com/apache/dubbo-admin/releases)
+
+3. Start dubbo-admin
+
+4. Visit: http:// localhost:8080
+
+5. Enter the "API Doc" module
+
+### Annotation use
+
+* @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
+ * 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
+ * value: parameter name
+ * required: true/false required parameter
+ * description: parameter description
+ * example: parameter example
+ * 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
+ * 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.
+> 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
+* 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/content/zh/docs/v2.7/admin/ops/apidocs.md b/content/zh/docs/v2.7/admin/ops/apidocs.md
new file mode 100644
index 0000000..35300a0
--- /dev/null
+++ b/content/zh/docs/v2.7/admin/ops/apidocs.md
@@ -0,0 +1,101 @@
+---
+type: docs
+title: "API文档&测试"
+linkTitle: "API文档&测试"
+weight: 4
+---
+
+## dubbo api docs
+
+dubbo 接口文档、测试工具,根据注解生成文档,并提供测试功能.
+
+增加一些注解就能生成类似swagger的文档, 不会把非web的dubbo项目变为web项目.
+
+## 如何使用?
+
+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版本号
+
+```
+<dependency>
+ <groupId>org.apache.dubbo</groupId>
+ <artifactId>dubbo-api-docs-annotations</artifactId>
+ <version>${dubbo-version}</version>
+</dependency>
+
+<dependency>
+ <groupId>org.apache.dubbo</groupId>
+ <artifactId>dubbo-api-docs-core</artifactId>
+ <version>${dubbo-version}</version>
+</dependency>
+```
+
+2. 下载 [dubbo-admin](https://github.com/apache/dubbo-admin) [下载地址](https://github.com/apache/dubbo-admin/releases)
+
+3. 启动 dubbo-admin
+
+4. 访问: http:// localhost:8080
+
+5. 进入"接口文档"模块
+
+### 注解使用
+
+* @EnableDubboApiDocs: 配制注解, 启用 dubbo api docs 功能
+* @ApiModule: 类注解, dubbo接口模块信息,用于标注一个接口类模块的用途
+ * value: 模块名称
+ * apiInterface: 提供者实现的接口
+ * version: 模块版本
+* @ApiDoc: 方法注解, dubbo 接口信息,用于标注一个接口的用途
+ * value: 接口名称
+ * description: 接口描述(可使用html标签)
+ * version: 接口版本
+ * responseClassDescription: 响应的数据的描述
+* @RequestParam: 类属性/方法参数注解,标注请求参数
+ * value: 参数名
+ * required: 是否必传参数
+ * description: 参数描述
+ * example: 参数示例
+ * defaultValue: 参数默认值
+ * allowableValues: 允许的值,设置该属性后界面上将对参数生成下拉列表
+ * 注:使用该属性后将生成下拉选择框
+ * boolean 类型的参数不用设置该属性,将默认生成 true/false 的下拉列表
+ * 枚举类型的参数会自动生成下拉列表,如果不想开放全部的枚举值,可以单独设置此属性.
+* @ResponseProperty: 类属性注解, 标注响应参数
+ * value: 参数名
+ * example: 示例
+
+### 使用注意
+
+* 获取接口列表直连:
+
+> 由于可能不同功能的dubbo服务都会注册到同一个注册中心,但是dubbo doc
+> 使用的接口名是一样的,所以dubbo doc的接口采用直连方式以获取到不同功能服务的不同接口列表
+> 测试可以直连或者走注册中心
+
+* 响应bean(接口的返回类型)支持自定义泛型, 但只支持一个泛型占位符
+* 关于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
diff --git a/static/imgs/admin/dubbo_docs_en.png b/static/imgs/admin/dubbo_docs_en.png
new file mode 100644
index 0000000..2fc0b44
Binary files /dev/null and b/static/imgs/admin/dubbo_docs_en.png differ
diff --git a/static/imgs/admin/dubbo_docs_zh.png b/static/imgs/admin/dubbo_docs_zh.png
new file mode 100644
index 0000000..7fd1d44
Binary files /dev/null and b/static/imgs/admin/dubbo_docs_zh.png differ