feat(apigw/sync_resource): support doc (TencentBlueKing#197)

Author: Han-Ya-Jun

sdks/apigw-manager/README.md

@@ -76,4 +76,9 @@ definition.yaml 指定的环境配置适用于 `sync_apigw_stage` 命令，而
 
 ### 6. 注册网关资源时如果只想注册生成版本，不进行版本发布，该如何操作？
 
-`create_version_and_release_apigw` 是进行网关资源生成版本和发布的命令，可以通过指定 `--no-pub` 只进行版本生成，不进行资源发布。
+`create_version_and_release_apigw` 是进行网关资源生成版本和发布的命令，可以通过指定 `--no-pub` 只进行版本生成，不进行资源发布。
+
+
+### 7. 同步网关资源的同时想直接根据 `resources.yaml` 即 swagger 或者 openapi3.0 生成文档，该如何操作？
+
+`sync_apigw_resources` 是进行网关资源同步命令，可以通过指定 `--doc_language`: en/zh 生成接口文档

sdks/apigw-manager/docs/sync-apigateway-with-django.md

@@ -34,6 +34,7 @@ python manage.py sync_apigw_stage --gateway-name=${gateway_name} --file="${defin
 # 
 # --delete: 当资源在服务端存在，却未出现在资源定义文件中时，指定本参数会强制删除这类资源，以保证服务端资源和文件内容完全一致。
 #           如果未指定本参数，将忽略未出现的资源
+# --doc_language: en/zh  是否生成接口文档(中文/英文)
 python manage.py sync_apigw_resources --delete --gateway-name=${gateway_name} --file="${resources_file}"
 
 # 可选，同步资源文档
@@ -169,7 +170,7 @@ python manage.py grant_apigw_permissions --gateway-name=${gateway_name} --file="
 # 同步网关基本信息
 python manage.py sync_apigw_config --gateway-name=${gateway_name} --file="${definition_file}"
 
-# 同步网关资源；--delete 将删除网关中未在 resources.yaml 存在的资源
+# 同步网关资源；--delete 将删除网关中未在 resources.yaml 存在的资源, 指定参数 --doc_language en/zh  是否生成接口文档(中文/英文)
 python manage.py sync_apigw_resources --delete --gateway-name=${gateway_name} --file="${resources_file}"
 
 # 同步网关环境信息

sdks/apigw-manager/docs/sync-apigateway-with-docker.md

@@ -72,6 +72,7 @@ call_command_or_warning migrate apigw
 title "syncing apigateway"
 call_definition_command_or_exit sync_apigw_config "${definition_file}" --gateway-name=${gateway_name}
 call_definition_command_or_exit sync_apigw_stage "${definition_file}" --gateway-name=${gateway_name}
+# --doc_language: en/zh  是否生成接口文档(中文/英文)
 call_definition_command_or_exit sync_apigw_resources "${resources_file}" --gateway-name=${gateway_name} --delete
 call_definition_command_or_exit sync_resource_docs_by_archive "${definition_file}" --gateway-name=${gateway_name} --safe-mode
 call_definition_command_or_exit grant_apigw_permissions "${definition_file}" --gateway-name=${gateway_name}
@@ -292,6 +293,7 @@ call_definition_command_or_exit sync_apigw_config "${definition_file}" --gateway
 # 
 # --delete: 当资源在服务端存在，却未出现在资源定义文件中时，指定本参数会强制删除这类资源，以保证服务端资源和文件内容完全一致。
 #           如果未指定本参数，将忽略未出现的资源
+# --doc_language: en/zh  是否生成接口文档(中文/英文)
 call_definition_command_or_exit sync_apigw_resources "${resources_file}" --gateway-name=${gateway_name} --delete
 
 # 同步网关环境信息

sdks/apigw-manager/src/apigw_manager/apigw/management/commands/sync_apigw_resources.py

@@ -30,6 +30,13 @@ def add_arguments(self, parser):
             help="delete extraneous resources from existing resources",
         )
 
+        parser.add_argument(
+            "--doc_language",
+            type=str,
+            default=None,
+            help="language for gen api doc: en/zh",
+        )
+
     def _update_signature(self, gateway_name, definition, added, deleted):
         signature = hashlib.md5(json.dumps(definition, sort_keys=True).encode("utf-8")).hexdigest()
 
@@ -41,7 +48,15 @@ def _update_signature(self, gateway_name, definition, added, deleted):
             manager.mark_dirty(gateway_name)
 
     def do(self, manager, definition, configuration, *args, **kwargs):
-        result = manager.sync_resources_config(content=definition, delete=kwargs["delete"])
+        sync_args = {
+            'content': definition,
+            'delete': kwargs["delete"],
+        }
+
+        if 'doc_language' in kwargs:
+            sync_args['doc_language'] = kwargs['doc_language']
+
+        result = manager.sync_resources_config(**sync_args)
 
         added_count = len(result["added"])
         deleted_count = len(result["deleted"])

sdks/apigw-manager/tests/apigw_manager/apigw/management/commands/test_sync_apigw_resources.py

@@ -41,11 +41,12 @@ def test_do(mocker, configuration, command, manager, resource_signature_manager)
     manager.sync_resources_config.return_value = result
     definition = {}
 
-    command.do(manager, definition, configuration, delete=True)
+    command.do(manager, definition, configuration, delete=True,doc_language="en")
 
     manager.sync_resources_config.assert_called_once_with(
         content=definition,
         delete=True,
+        doc_language="en"
     )
     resource_signature_manager.update_signature.assert_called_once_with(configuration.gateway_name, mocker.ANY)
     resource_signature_manager.mark_dirty.assert_called_once_with(configuration.gateway_name)