fix(cr): fix comments

sdks/apigw-manager/src/apigw_manager/drf/management/commands/generate_definition_yaml.py

@@ -8,11 +8,10 @@
 # specific language governing permissions and limitations under the License.
 
 """
-this command will generate the resources.yaml from the drf_spectacular config of the apis under project
+this command will generate the definition.yaml
 
-if only want part of the apis:
-1. add the `tags` in `@extend_schema` of each method in the views.py
-2. call this command with tag, e.g. `python manage.py generate_resource_yaml.py --tag=foo --tag=bar`
+it will copy a template definition.yaml from apigw_manager into the project. And if the version of apigw_manager changes,
+the template definition.yaml will be updated.
 """
 
 import os

sdks/apigw-manager/src/apigw_manager/drf/management/commands/sync_apigateway.py → sdks/apigw-manager/src/apigw_manager/drf/management/commands/sync_drf_apigateway.py

@@ -8,17 +8,20 @@
 # specific language governing permissions and limitations under the License.
 
 """
-this command will sync the apis to bk-apigateway
+this command will sync the apis of current project to bk-apigateway
 
 the related files for syncing:
 - config/settings.py (the settings values for the gateway)
 - definition.yaml (generated by command `generate_definition_yaml`, the template, will be rendered with the settings)
 - resources.yaml (generated by command `generate_resource_yaml`, the api definitions of the gateway)
 
 reference: https://github.com/TencentBlueKing/bkpaas-python-sdk/blob/master/sdks/apigw-manager/docs/sync-apigateway-with-django.md
-"""
 
-import os
+the steps of syncing
+1. generate definition.yaml:  `python manage.py generate_definition_yaml`
+2. generate resources.yaml: `python manage.py generate_resources_yaml`
+3. do the sync
+"""
 
 from pathlib import Path
 from django.conf import settings

sdks/apigw-manager/src/apigw_manager/drf/utils.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# TencentBlueKing is pleased to support the open source community by making 蓝鲸智云-蓝鲸 PaaS 平台(BlueKing-PaaS) available.
+# TencentBlueKing is pleased to support the open source community by making 蓝鲸智云 - 蓝鲸 PaaS 平台 (BlueKing-PaaS) available.
 # Copyright (C) 2017-2021 THL A29 Limited, a Tencent company. All rights reserved.
 # Licensed under the MIT License (the "License"); you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at http://opensource.org/licenses/MIT
@@ -19,12 +19,26 @@ def gen_apigateway_resource_config(
     is_public: bool = True,
     allow_apply_permission: bool = True,
     user_verified_required: bool = False,
-    app_verified_required: bool = False,
-    resource_permission_required: bool = False,
+    app_verified_required: bool = True,
+    resource_permission_required: bool = True,
     description_en: str = "",
     plugin_configs: Optional[List[Dict]] = None,
     match_subpath: bool = False,
 ) -> Dict[str, Dict[str, any]]:
+    """用于辅助生成 bk-apigateway 的资源配置
+    Args:
+        is_public (bool, optional): 是否公开，不公开在文档中心/应用申请网关权限资源列表中不可见。默认 True
+        allow_apply_permission (bool, optional):  是否允许申请权限，不允许的话在应用申请网关权限资源列表中不可见。默认 True
+        user_verified_required (bool, optional): 是否开启用户认证 默认 False
+        app_verified_required (bool, optional): 是否开启应用认证。默认 True
+        resource_permission_required (bool, optional): 是否校验资源权限，是的话将会校验应用是否有调用这个资源的权限，前置条件：开启应用认证。默认 True
+        description_en (str, optional): 资源的英文描述。默认 ""
+        plugin_configs (Optional[List[Dict]], optional): 插件配置，类型为 List[Dict], 用于声明作用在这个资源上的插件，可以参考官方文档。默认 None.
+        match_subpath (bool, optional): 匹配所有子路径，默认为 False. 默认 False
+    Returns:
+        Dict[str, Dict[str, any]]: _description_
+    """
+
     # resource_permission_required  need app_verified_required
     if not app_verified_required:
         resource_permission_required = False
@@ -57,14 +71,24 @@ def gen_apigateway_resource_config(
     }
 
 
-# reference: https://github.com/TencentBlueKing/blueapps/blob/master/blueapps/conf/log.py
-# changed
 def get_logging_config_dict(
     log_level: str,
     is_local: bool,
     log_dir: str,
     app_code: str,
 ):
+    """用户生成蓝鲸 PaaS 运行时的 Django Logging 配置
+    来源于蓝鲸开发框架，以获取最大的兼容性 reference: https://github.com/TencentBlueKing/blueapps/blob/master/blueapps/conf/log.py
+
+    Args:
+        log_level (str): 日志级别
+        is_local (bool): 是否是本地开发，本地开发日志格式为文本格式，线上环境为 json 格式
+        log_dir (str): 日志文件所在目录
+        app_code (str): 应用 app_code
+
+    Returns:
+        logging config dict
+    """
     log_class = "concurrent_log_handler.ConcurrentRotatingFileHandler"
 
     if is_local:
@@ -185,8 +209,17 @@ def get_logging_config_dict(
     }
 
 
-# reference: https://github.com/TencentBlueKing/blueapps/blob/master/blueapps/conf/database.py
 def get_default_database_config_dict(settings_module):
+    """用户生成蓝鲸 PaaS 运行时的 Django Database 配置
+    由于蓝鲸 PaaS 内外版本差异，数据库相关的环境变量有所不同，所以需要通过这个函数做版本差异兼容。
+    来源于蓝鲸开发框架，以获取最大的兼容性 reference: https://github.com/TencentBlueKing/blueapps/blob/master/blueapps/conf/database.py
+
+    Args:
+        django settings locals() 配置
+
+    Returns:
+        database config dict
+    """
     if os.getenv("GCS_MYSQL_NAME") and os.getenv("MYSQL_NAME"):
         db_prefix = settings_module.get("DB_PREFIX", "")
         if not db_prefix: