docs(docs/sync_apigateway.md): update doc for sync_apigateway (TencentBlueKing#225)

Author: wklken

sdks/apigw-manager/docs/sync_apigateway.md

@@ -2,25 +2,25 @@
 
 SDK 同步网关配置到 API 网关，支持多种方案：
 
-- [直接使用 Django Command 同步](./sync-apigateway-with-django.md)：此方案适用于 Django 项目；Django 项目，可直接执行 SDK 提供的 Django Command 指令
-- [通过镜像方式同步](./sync-apigateway-with-docker.md)：此方案适用于非 Django 项目；非 Django 项目，无法直接执行 SDK 提供的 Django Command 指令
+- [直接使用 Django Command 同步](./sync-apigateway-with-django.md)：此方案适用于 `Django 项目`；(可直接执行 SDK 提供的 Django Command 指令)
+- [通过镜像方式同步](./sync-apigateway-with-docker.md)：此方案适用于 `非 Django 项目`；(无法直接执行 SDK 提供的 Django Command 指令)
 
 ## 1. 准备工作
 
 同步网关配置到 API 网关，需要准备网关配置、资源配置、资源文档、自定义同步脚本等数据，可参考目录：
 
 ```shell
 support-files
-├── definition.yaml         # 维护网关、环境、资源文档路径、主动授权、发布等配置，但不包含资源配置
-├── resources.yaml          # 维护资源配置；资源配置可通过 API 网关管理端直接导出，数据量较大，因此单独管理
-├── bin
-│   └── sync-apigateway.sh  # 自定义同步脚本，Django 项目也可以自定义 Django Command
-├── bk_apigw_docs_demo.tgz  # 资源文档归档文件，可选；可通过 API 网关管理端导出；与资源文档目录 apidocs 二选一
-└── apidocs                 # 资源文档目录，可选；可通过 API 网关管理端导出并解压，或者直接维护 markdown 格式文档文件
-    ├── zh                  # 中文文档目录
-    │   └── anything.md
-    └── en                  # 英文文档目录
-        └── anything.md
+  ├── definition.yaml         # 维护网关、环境、资源文档路径、主动授权、发布等配置，但不包含资源配置
+  ├── resources.yaml          # 维护资源配置；资源配置可通过 API 网关管理端直接导出，数据量较大，因此单独管理
+  ├── bin
+  │   └── sync-apigateway.sh  # 自定义同步脚本，Django 项目也可以自定义 Django Command
+  ├── bk_apigw_docs_demo.tgz  # 资源文档归档文件，可选；可通过 API 网关管理端导出；与资源文档目录 apidocs 二选一
+  └── apidocs                 # 资源文档目录，可选；可通过 API 网关管理端导出并解压，或者直接维护 markdown 格式文档文件
+      ├── zh                  # 中文文档目录
+      │   └── anything.md
+      └── en                  # 英文文档目录
+          └── anything.md
 ```
 
 ### 1.1 definition.yaml
@@ -44,19 +44,21 @@ support-files
 
 definition.yaml 中可以使用 Django 模版语法引用和渲染变量，内置以下变量：
 
-- `settings`：Django 提供的配置对象，优先适合用于使用 Django Command 同步
-- `environ`：环境变量，推荐镜像同步方式使用
+- `settings`：Django 提供的配置对象，适合用于使用 Django Command 同步
+- `environ`：环境变量，适合用于通过镜像方式同步方式使用
 
 推荐在一个文件中统一进行定义，用命名空间区分不同配置间的定义，definition.yaml 样例：
 
-目前有两种配置文件版本：spec_version=1/2，主要区别就是 stage 相关的配置方式上有一些不一样。
-新接入系统请使用 spec_version=2，旧有系统如果需要配置多个 stage/配置多个 backend，建议也升级到 spec_version=2 并变更相关 yaml 配置。
-区别如下：
-spec_version: 1
+注意：
+
+- 目前有两种配置文件版本：`spec_version=1/2`, 主要区别是 stage 相关的配置方式上不一样
+- 新接入系统请使用 `spec_version=2`
+- 旧有系统如果需要配置多个 stage/配置多个 backend，建议也升级到 `spec_version=2` 并变更相关 yaml 配置
+
+> spec_version: 1 (deprecated, 不推荐使用)
 
 ```yaml
-# definition.yaml 配置文件版本号，必填，固定值 1/2
-# 1：key 为 stage; 只支持单个 stage，并且 proxy_http 只能配置一个后端服务
+# spec_version: 1 => key 为 stage; 只支持单个 stage，并且 proxy_http 只能配置一个后端服务
 spec_version: 1
 stage:
   name: "prod"
@@ -71,11 +73,10 @@ stage:
           weight: 100
 ```
 
-spec_version: 2
+> spec_version: 2 (推荐使用)
 
 ```yaml
-# definition.yaml 配置文件版本号，必填，固定值 1/2
-# 2：key 为 stages; 支持多个 stages，并且每个 stage 可以配置多个 backend 后端服务
+# spec_version: 2 => key 为 stages; 支持多个 stages，并且每个 stage 可以配置多个 backend 后端服务
 spec_version: 2
 stages:
   - name: "prod"
@@ -101,13 +102,12 @@ stages:
               weight: 100
 ```
 
-> 📢 注意：如果之前接入过的，建议将 sepc_version 改成 2，并将原先 `stage:{}`改成 `stages: []`
+> 📢 注意：如果之前接入过的，建议将 spec_version 改成 2，并将原先 `stage:{}`改成 `stages: []`
 
 整体的样例：
 
 ```yaml
-# definition.yaml 配置文件版本号，必填，固定值 1/2
-spec_version: 2  # 如果之前接入过的，建议将 sepc_version 改成 2，并将原先 stage:改成 stages: []
+spec_version: 2  # 如果之前接入过的，建议将 spec_version 改成 2，并将原先 stage:改成 stages: []
 
 # 定义发布内容，用于命令 `create_version_and_release_apigw`，具体生效的环境取决于参数 --stage prod test 等方式来指定
 release:
@@ -126,7 +126,7 @@ apigateway:
   description_en: "English description"
   # 是否公开；公开，则用户可查看资源文档、申请资源权限；不公开，则网关对用户隐藏
   is_public: true
-  # 标记网关为官方网关，网关名需以 `bk-` 开头，可选；非官方网关，可去除此配置
+  # 标记网关为官方网关，网关名需以 `bk-` 开头，可选；非官方网关，去除此配置
   api_type: 1
   # 网关维护人员，仅维护人员有管理网关的权限
   maintainers:
@@ -237,10 +237,36 @@ resource_docs:
 
 ### 1.2 resources.yaml
 
-用于定义资源配置，建议通过网关管理端导出。为了方便用户直接使用网关导出的资源文件，资源定义默认没有命名空间。
+用于定义资源配置，建议通过**网关管理端导出**。为了方便用户直接使用网关导出的资源文件，资源定义默认没有命名空间。
+
+- 可以在产品端表单录入所有资源后导出，用于其他环境的自动化注册配置
+- [建议] 从程序中直接导出 swagger 或 openapi 定义，然后在网关产品端导入后，根据实际需求调整配置，发布测试确认没问题后，导出资源配置作为其他环境的自动化注册配置
 
 样例可参考：[resources.yaml](../examples/django/use-custom-script/support-files/resources.yaml)
 
+字段配置说明：
+
+```yaml
+x-bk-apigateway-resource:
+  isPublic: true   # 是否公开，公开，则用户可查看资源文档、申请资源权限；不公开，则资源对用户隐藏
+  allowApplyPermission: false # 是否允许用户申请资源权限，允许，则任何蓝鲸应用可在蓝鲸开发者中心申请资源的访问权限；否则，只能通过网关管理员主动授权为某应用添加权限
+  matchSubpath: false # 匹配所有子路径
+  backend:
+    type: HTTP
+    method: get
+    path: /anything
+    matchSubpath: false
+    timeout: 0
+    upstreams: {}
+    transformHeaders: {}
+  pluginConfigs: [] # 插件配置
+  authConfig:
+    appVerifiedRequired: true  # 是否开启应用认证，开启后请求方需提供蓝鲸应用身份信息
+    userVerifiedRequired: false # 是否开启用户认证，请求方需提供蓝鲸用户身份信息
+    resourcePermissionRequired: false # 是否校验应用权限，开启后，蓝鲸应用需申请资源访问权限; 前提必须开启应用认证；
+  descriptionEn: # 资源描述的英文翻译
+```
+
 > 详细的插件配置见：[插件配置说明](./plugin-use-guide.md)
 
 ### 1.3 apidocs（可选）
@@ -271,10 +297,11 @@ resource_docs:
 - 网关采用 Jinja 模板 支持文档文件的引用。对于需采用 Jinja 模板渲染的资源文档，需将文件名后缀设置为 .md.j2
 - 对于被引用的公共文档片段，文件名可以以下划线（_）开头。
 
-> 网关导入文档时，将分别进入 zh、en 目录，处理中文、英文文档，不同类型的文档，处理方式不同：
-> - .md 为后缀的文档，将直接读取文档内容
-> - .md.j2 为后缀的文档，将以文档所在目录为基准，采用 Jinja 模板进行渲染
-> - 下划线 (_) 开头的文档，将跳过解析，此类文档为公共文档片段，非具体资源的文档
+网关导入文档时，将分别进入 zh、en 目录，处理中文、英文文档，不同类型的文档，处理方式不同：
+
+- .md 为后缀的文档，将直接读取文档内容
+- .md.j2 为后缀的文档，将以文档所在目录为基准，采用 Jinja 模板进行渲染
+- 下划线 (_) 开头的文档，将跳过解析，此类文档为公共文档片段，非具体资源的文档
 
 例如资源 get_user，采用 Jinja 模板渲染时，其文档文件名应为 get_user.md.j2，其引用其它文档示例如下：
 
@@ -341,22 +368,22 @@ stage:
 
 ```yaml
 x-bk-apigateway-resource:
-isPublic: false
-allowApplyPermission: false
-matchSubpath: false
-backend:
-  type: HTTP
-  method: get
-  path: /anything
+  isPublic: false
+  allowApplyPermission: false
   matchSubpath: false
-  timeout: 0
-  upstreams: {}
-  transformHeaders: {}
-authConfig:
-  appVerifiedRequired: true
-  userVerifiedRequired: false
-  resourcePermissionRequired: false
-descriptionEn: anything
+  backend:
+    type: HTTP
+    method: get
+    path: /anything
+    matchSubpath: false
+    timeout: 0
+    upstreams: {}
+    transformHeaders: {}
+  authConfig:
+    appVerifiedRequired: true
+    userVerifiedRequired: false
+    resourcePermissionRequired: false
+  descriptionEn: anything
 ```
 
 ## 2. 同步方案