From 764ebe6dcbf6b219b7213b42610c50cf13a98177 Mon Sep 17 00:00:00 2001 From: hanyajun <1581532052@qq.com> Date: Fri, 25 Oct 2024 11:40:53 +0800 Subject: [PATCH] feat(apigw/sync_resource): support doc (#197) --- sdks/apigw-manager/README.md | 7 ++++++- .../docs/sync-apigateway-with-django.md | 3 ++- .../docs/sync-apigateway-with-docker.md | 2 ++ .../management/commands/sync_apigw_resources.py | 17 ++++++++++++++++- .../commands/test_sync_apigw_resources.py | 3 ++- 5 files changed, 28 insertions(+), 4 deletions(-) diff --git a/sdks/apigw-manager/README.md b/sdks/apigw-manager/README.md index 30b67167..79ab48d1 100644 --- a/sdks/apigw-manager/README.md +++ b/sdks/apigw-manager/README.md @@ -76,4 +76,9 @@ definition.yaml 指定的环境配置适用于 `sync_apigw_stage` 命令，而 ### 6. 注册网关资源时如果只想注册生成版本，不进行版本发布，该如何操作？ -`create_version_and_release_apigw` 是进行网关资源生成版本和发布的命令，可以通过指定 `--no-pub` 只进行版本生成，不进行资源发布。 \ No newline at end of file +`create_version_and_release_apigw` 是进行网关资源生成版本和发布的命令，可以通过指定 `--no-pub` 只进行版本生成，不进行资源发布。 + + +### 7. 同步网关资源的同时想直接根据 `resources.yaml` 即 swagger 或者 openapi3.0 生成文档，该如何操作？ + +`sync_apigw_resources` 是进行网关资源同步命令，可以通过指定 `--doc_language`: en/zh 生成接口文档 \ No newline at end of file diff --git a/sdks/apigw-manager/docs/sync-apigateway-with-django.md b/sdks/apigw-manager/docs/sync-apigateway-with-django.md index a40a0628..7a272ded 100644 --- a/sdks/apigw-manager/docs/sync-apigateway-with-django.md +++ b/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}" # 同步网关环境信息 diff --git a/sdks/apigw-manager/docs/sync-apigateway-with-docker.md b/sdks/apigw-manager/docs/sync-apigateway-with-docker.md index 89439072..d721c748 100644 --- a/sdks/apigw-manager/docs/sync-apigateway-with-docker.md +++ b/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 # 同步网关环境信息 diff --git a/sdks/apigw-manager/src/apigw_manager/apigw/management/commands/sync_apigw_resources.py b/sdks/apigw-manager/src/apigw_manager/apigw/management/commands/sync_apigw_resources.py index 0872f78f..156907fb 100644 --- a/sdks/apigw-manager/src/apigw_manager/apigw/management/commands/sync_apigw_resources.py +++ b/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"]) diff --git a/sdks/apigw-manager/tests/apigw_manager/apigw/management/commands/test_sync_apigw_resources.py b/sdks/apigw-manager/tests/apigw_manager/apigw/management/commands/test_sync_apigw_resources.py index f2ce3dbc..dc9cbacd 100644 --- a/sdks/apigw-manager/tests/apigw_manager/apigw/management/commands/test_sync_apigw_resources.py +++ b/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)