This is an automated email from the ASF dual-hosted git repository.
dengliming pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/shenyu-website.git
The following commit(s) were added to refs/heads/main by this push:
new 62495ab1ed [DOC] add api doc table design (#775)
62495ab1ed is described below
commit 62495ab1edd8246441109b13094a5bbafa13acc7
Author: dragon-zhang <[email protected]>
AuthorDate: Sat Oct 1 16:13:55 2022 +0800
[DOC] add api doc table design (#775)
Co-authored-by: hailang <[email protected]>
---
docs/design/database-design.md | 21 +++++++++++++++++++++
.../current/design/database-design.md | 21 +++++++++++++++++++++
static/img/shenyu/db/shenyu-api-doc-table.png | Bin 0 -> 146423 bytes
3 files changed, 42 insertions(+)
diff --git a/docs/design/database-design.md b/docs/design/database-design.md
index daa211d9a5..89e391b52b 100644
--- a/docs/design/database-design.md
+++ b/docs/design/database-design.md
@@ -71,4 +71,25 @@ Apache Shenyu Admin is the management system of the gateway,
which can manage al
<img src="/img/shenyu/db/shenyu_dict.png" width="30%" height="30%" />
+## API Documentation {#API-documentation}
+* The API document tables used to maintain and manage API documents.
+* The API document (such as json, md, html, etc.) of common specifications
(such as OpenApi3.0 and yapi) can be imported into `shenyu-admin` and finally
stored in the API document tables.
+* API documents of other common specifications can be generated through the
API document tables.
+* The Database Table UML Diagram:
+
+ <img src="/img/shenyu/db/shenyu-api-doc-table.png" width="30%" height="30%"
/>
+
+* Detailed design:
+ * A tag can have multiple child tags, the level of tags is unlimited, the
lowest leaf node is API.
+ * Interfaces with the same path but supporting multiple http methods, they
are counted as multiple APIs.
+ * An API has multiple request parameters and response fields.
+ * A parameter/field has its own type (model), and each type have multiple
fields.
+ * A field has its own type, which corresponds to multiple values.
+ * A value can be used as either a request example value, or a response
example value (for example, 200 indicates OK, and 400 indicates illegal
parameters).
+ * The `query`, `header` and `body`, all of them are `json` stored in
`mock_request_record`，but `body` does not support special types such as file。
+ * The `ext` of the `tag` table stores the full amount of json data of its
parent tag (including the parent tag of the parent tag, and so on).
+ * The `ext` of the `api` table may store the IP list and the service name of
`SpringCloud`.
+ * The `type` of the `parameter` table mainly includes `requestUrlParam`,
`requestHeader`, `requestBody`, `requestPathVariable`, `responseHeader`, and
`responseBody`; If the returned type is a special type (such as file), do not
associate `model_id`.
+ * The `ext` of the `field` table stores generic type in json format
(convenient for subsequent expansion), such as `{"genericTypes": [model_id1,
model_id2]}`; `model_id` indicates which type has this field, `self_model_id`
indicates which type of this field.
+ * The `is_example` of `detail` table indicates whether a value is a request
sample value, true is a request sample value, and false is a response value.
diff --git
a/i18n/zh/docusaurus-plugin-content-docs/current/design/database-design.md
b/i18n/zh/docusaurus-plugin-content-docs/current/design/database-design.md
index 2ecb2753f5..0b878f0f83 100644
--- a/i18n/zh/docusaurus-plugin-content-docs/current/design/database-design.md
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/design/database-design.md
@@ -71,4 +71,25 @@ description: ShenYu Admin数据结构
<img src="/img/shenyu/db/shenyu_dict.png" width="30%" height="30%" />
+## API文档
+* API文档表用来维护和管理API文档。
+* 常见规范(如OpenApi3.0规范、yapi规范)的api
doc(如json、md、html等)可以导入`shenyu-admin`，并最终存储到API文档表。
+* 通过API文档表可以生成其他常见规范的api doc。
+* 数据库 `UML` 类图：
+
+ <img src="/img/shenyu/db/shenyu-api-doc-table.png" width="30%" height="30%"
/>
+
+* 设计详解：
+ * 一个tag可以有多个子tag，tag的层级无限，最下面的叶子节点是API。
+ * 相同path、支持多种http_method的接口，算多个API。
+ * 一个API有多个请求参数、多个响应字段。
+ * 一个参数/字段有它自己的类型(也就是model)，每个类型由多个字段构成。
+ * 一个字段有它自己的类型，对应多个值。
+ * 一个值既可以作为请求示例值，也可以描述响应示例值(比如200表示OK、400表示非法参数)。
+ *
`mock_request_record`表的`query`、`header`、`body`都存储json，但是`body`不支持存储特殊类型(比如文件)。
+ * `tag`表的`ext`存储它父tag(包括父tag的父tag，以此类推)的全量json数据。
+ * `api`表的`ext`可能存储ip列表、SpringCloud的service name。
+ *
`parameter`表的`type`主要包括`requestUrlParam`、`requestHeader`、`requestBody`、`requestPathVariable`、`responseHeader`和`responseBody`；如果返回的类型是特殊类型(如文件)，则不用关联`model_id`。
+ *
`field`表的`ext`以json格式(方便后续扩展)存储泛型，如`{"genericTypes":[model_id1,model_id2]}`；`model_id`表示该字段属于哪个类型，`self_model_id`表示该字段自身是什么类型。
+ * `detail`表的`is_example`表示一个值是否是请求示例值，true是请求示例值，false是响应值。
diff --git a/static/img/shenyu/db/shenyu-api-doc-table.png
b/static/img/shenyu/db/shenyu-api-doc-table.png
new file mode 100644
index 0000000000..cc27f0e255
Binary files /dev/null and b/static/img/shenyu/db/shenyu-api-doc-table.png
differ
