Skip to content

Commit 2ca60c8

Browse files
wivwivwivwiv
committed
Update api doc and new upgrade process
1 parent c2d9281 commit 2ca60c8

File tree

9 files changed

+98345
-93279
lines changed

9 files changed

+98345
-93279
lines changed

‎.github/workflows/deploy_docs.yaml

-2
Original file line numberDiff line numberDiff line change
@@ -113,7 +113,6 @@ jobs:
113113
mkdir -p frontend/redoc/
114114
cp -r docs-files/en_US/* frontend/docs/en/${VERSION}/
115115
cp -r docs-files/zh_CN/* frontend/docs/zh/${VERSION}/
116-
cp -r docs-files/swagger/* frontend/docs/.vuepress/public/api/
117116
cp -r docs-files/redocly/*.json frontend/redoc/
118117
cp docs-files/directory.json frontend/docs/.vuepress/config/directory.json
119118
@@ -130,7 +129,6 @@ jobs:
130129
mkdir -p frontend/redoc/
131130
cp -r docs-files/en_US/* frontend/docs/en/${DOCS_TYPE}/${VERSION}/
132131
cp -r docs-files/zh_CN/* frontend/docs/zh/${DOCS_TYPE}/${VERSION}/
133-
cp -r docs-files/swagger/* frontend/docs/.vuepress/public/api/
134132
cp -r docs-files/redocly/*.json frontend/redoc/
135133
cp docs-files/directory_ee.json frontend/docs/.vuepress/config/directory.json
136134

‎DOCS-WRITING-GUIDE-CN.md

+9-25
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,7 @@
1717
- [资源引用](#资源引用)
1818
- [特殊语法](#特殊语法)
1919
- [差异化编译](#差异化编译)
20-
- [OpenAPI](#openapi)
21-
- [EMQX 的 API 文档](#emqx-的-api-文档)
20+
- [EMQX 的 API 文档](#emqx-的-api-文档)
2221
- [配置文档更新](#配置文档更新)
2322
- [Commands to copy generated markdown](#commands-to-copy-generated-markdown)
2423

@@ -221,36 +220,21 @@ or
221220
contents {% endemqxee %}
222221
```
223222

224-
### OpenAPI
223+
### EMQX 的 API 文档
225224

226-
EMQX API 文档是自动生成的。
227-
文档其实是一个 OpenAPI 3.0 规范的 JSON 格式的描述文件。
225+
EMQX 首先自动生成了一个 OpenAPI 3.0 规范的 JSON 格式的描述文件(swagger.json)，之后将其通过 [Redocly](https://github.com/Redocly/redoc) 渲染展示。
228226

229-
在 vue.js 插件的帮助下，OpenAPI 的文档可以像下面这个例子一样嵌入到 markdown 文档中的任意位置。
230-
231-
```markdown
232-
<ClientOnly>
233-
<OpenApi path="swagger.json" />
234-
</ClientOnly>
235-
```
236-
237-
路径（ path ） 参数用于指定使用哪个文件。
238-
文件必需放置在 `swagger` 这个子目录中。
239-
240-
#### EMQX 的 API 文档
241-
242-
EMQX 的 API 文档嵌入到了 `admin/api.md` 中。
243-
244-
`swagger.json` 的内容最初是 EMQX 中的 HTTP 服务组件自动生成的，
245-
当前 git 仓库里的文件则是通过 EMQX 生成的文件做一定的改写生成的。
246-
247-
如果需要更新 API 文档，步骤如下：
227+
swagger.json 文件保存在 `./redocly` 目录下，在每个 EMQX 正式版本发布后需要更新 API 文档，步骤如下：
248228

249229
- 启动最新的 EMQX v5 的节点
250-
- 执行当前仓库里的脚本 `./rewrite-swagger.sh ce | ee`
230+
- 需要区分开源版/企业版
231+
- 需要通过 `dashboard.i18n_lang = en | zh` 配置项设置 swagger.json 输出语言
232+
- 根据版本以及语言执行当前仓库里的脚本 `./rewrite-swagger.sh <ce | ee> [en | zh]`
251233
- 将修改后的文件提交到 git 版本中
252234
- 发送一个 GitHub PR
253235

236+
你也可以上传 swagger.json 到 <https://redocly.github.io/redoc/> 预览 API 文档渲染结果。
237+
254238
### 配置文档更新
255239

256240
配置文档是自动生成的。下面列出了更新的步骤。

‎DOCS-WRITING-GUIDE-EN.md

+10-26
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,7 @@
1717
- [Resource reference](#resource-reference)
1818
- [Special grammars](#special-grammars)
1919
- [Differentiated compilation](#differentiated-compilation)
20-
- [OpenAPI](#openapi)
21-
- [EMQX API doc](#emqx-api-doc)
20+
- [EMQX API doc](#emqx-api-doc)
2221
- [Configuration](#configuration)
2322
- [Commands to copy generated markdown](#commands-to-copy-generated-markdown)
2423

@@ -219,36 +218,21 @@ or
219218
contents {% endemqxee %}
220219
```
221220

222-
### OpenAPI
221+
### EMQX API doc
223222

224-
EMQX API document is generated.
225-
The document is essentially an OpenAPI 3.0 specification in JSON format.
223+
EMQX first automatically generates a JSON formatted description file (swagger.json) that conforms to the OpenAPI 3.0 specification. It is then rendered and displayed using [Redocly](https://github.com/Redocly/redoc).
226224

227-
With the help of vue.js plugin, an OpenAPI specification can be inserted anywhere in a markdown document like below.
225+
The swagger.json file is saved in the `./redocly` directory. After each official release of the EMQX version, the API documentation needs to be updated by following the steps below:
228226

229-
```markdown
230-
<ClientOnly>
231-
<OpenApi path="swagger.json"/>
232-
</ClientOnly>
233-
```
234-
235-
The path is the OpenAPI specification file,
236-
and the file needs to be placed in the `swagger` sub-directory of the document root.
237-
238-
#### EMQX API doc
239-
240-
For EMQX API specification, the wrapping markdown file is `admin/api.md`.
241-
242-
`swagger.json` is originally generated by the HTTP server component runngin in EMQX,
243-
and then downloaded into this repo with some rewrites.
244-
245-
To update the file:
246-
247-
- Start EMQX v5 node
248-
- Execute the script `./rewrite-swagger.sh ce | ee`
227+
- Start the latest EMQX v5 node
228+
- Need to distinguish between the open source version and enterprise version
229+
- Need to configure swagger.json output language by `dashboard.i18n_lang = en | zh`
230+
- Execute the `./rewrite-swagger.sh <ce | ee> [en | zh]` script in the current repository according to the version and language
249231
- Commit the changed swagger.json file to this git repo
250232
- Send a pull request
251233

234+
You can also upload swagger.json to <https://redocly.github.io/redoc/> to preview the API doc rendering results.
235+
252236
### Configuration
253237

254238
The configuration docs are generated from source code.

‎redocly/ce-en.json

+49,159-1
Large diffs are not rendered by default.

‎redocly/ce-zh.json

+49,159-1
Large diffs are not rendered by default.

‎rewrite-swagger.sh

+8-20
Original file line numberDiff line numberDiff line change
@@ -5,47 +5,35 @@
55
set -euo pipefail
66

77
PROFILE="${1:-}"
8+
LANG="${2:-"en"}"
89
SWAGGER_DOWNLOAD_DEFAULT_URI="http://localhost:18083/api-docs/swagger.json"
10+
SWAGGER_INPUT="${3:-"$SWAGGER_DOWNLOAD_DEFAULT_URI"}"
911

1012
case "$PROFILE" in
1113
ce)
12-
TARGET_FILE='swagger/swagger.json'
14+
TARGET_FILE="redocly/ce-$LANG.json"
1315
;;
1416
ee)
15-
TARGET_FILE='swagger/swagger-ee.json'
17+
TARGET_FILE="redocly/ee-$LANG.json"
1618
;;
1719
*)
18-
echo "Usage $0 ce|ee [SWAGGER_INPUT]"
20+
echo "Usage $0 ce|ee [en|zh] [SWAGGER_INPUT]"
1921
echo "The optional parameter SWAGGER_INPUT can be the generated json file"
2022
echo "Otherwise it downloads the JSON file from $SWAGGER_DOWNLOAD_DEFAULT_URI"
2123
exit 1
2224
;;
2325
esac
2426

25-
SWAGGER_INPUT="${2:-"$SWAGGER_DOWNLOAD_DEFAULT_URI"}"
26-
2727
## download swagger from EMQX api-docs
2828
if [ -f "$SWAGGER_INPUT" ]; then
2929
echo "Using swagger JSON file $SWAGGER_INPUT"
3030
SWAGGER_INPUT_FILE="$SWAGGER_INPUT"
3131
else
32-
SWAGGER_INPUT_FILE='/tmp/swagger-filter-stage0.json'
32+
SWAGGER_INPUT_FILE='/tmp/emqx-swagger.json'
3333
echo "Downloading swagger JSON from $SWAGGER_INPUT"
3434
curl "$SWAGGER_INPUT" > "$SWAGGER_INPUT_FILE"
3535
fi
3636

37-
## change the deprecated endpoints to "__DEPRECATED__"
38-
(jq 'walk( if type == "object" then ( if .deprecated == true then "__DEPRECATED__" else . end ) else . end)' > /tmp/swagger-filter-stage1.json)<"$SWAGGER_INPUT_FILE"
39-
40-
## if a path has all methods "__DEPRECATED__", change the path to "__DEPRECATED__"
41-
(jq 'def all_deprecated: to_entries | length > 0 and all(.value == "__DEPRECATED__"); walk ( if type == "object" then ( if all_deprecated then "__DEPRECATED__" else . end ) else . end)' > /tmp/swagger-filter-stage2.json)</tmp/swagger-filter-stage1.json
42-
43-
## drop all "__DEPRECATED__" paths
44-
## or single deprecated methods
45-
(jq 'walk ( if type == "object" then with_entries(select(.value != "__DEPRECATED__")) else . end)' > /tmp/swagger-filter-stage3.json)</tmp/swagger-filter-stage2.json
46-
47-
## tags.json has been manullay tweaked for ordering
48-
TAGS="$(cat 'swagger/tags.json')"
37+
# TODO i18n file check
4938

50-
## prepend the tags to swagger body
51-
(jq "$TAGS + ." > "$TARGET_FILE") </tmp/swagger-filter-stage3.json
39+
cat $SWAGGER_INPUT_FILE | jq --indent 2 . > $TARGET_FILE

0 commit comments

Comments
 (0)