Swagger Codegen Python存根再生与自定义代码保留最佳实践咨询

以下是几种可靠的方案，按推荐程度排序：

1. 核心逻辑与生成代码彻底分离（最推荐） #

不要在Codegen生成的控制器文件（比如default_controller.py）中编写实际业务逻辑，而是将自定义代码放到独立的服务层模块中，生成的控制器仅作为转发层存在。

具体步骤： #

• 创建独立的服务模块，比如swagger_server/services/pet_service.py，在其中实现add_pet的实际逻辑：

  from swagger_server.models.pet import Pet
  
  def add_pet(body):
      # 这里编写自定义逻辑：比如存入数据库、参数校验、业务处理等
      new_pet = Pet(id=123, name=body.name, status="available")
      return new_pet
  

• 在生成的控制器文件中，仅保留参数解析和服务层调用：

  import connexion
  import six
  
  from swagger_server.models.pet import Pet
  from swagger_server import util
  # 导入自定义服务层
  from swagger_server.services.pet_service import add_pet as pet_service_add_pet
  
  def add_pet(body):  # noqa: E501
      """Add a new pet to the store
      ...（自动生成的注释保留）
      """
      if connexion.request.is_json:
          body = Pet.from_dict(connexion.request.get_json())
      # 转发请求到服务层处理
      return pet_service_add_pet(body)
  

• 后续重新生成存根时，只需确保控制器中的服务层调用逻辑被保留（若生成器覆盖了这部分，手动补回即可，或通过自定义模板避免重复操作）。

2. 自定义Swagger Codegen模板 #

通过修改Codegen的Python模板，让生成的控制器文件自动包含服务层调用代码，彻底避免手动修改生成文件。

具体步骤： #

• 从Swagger Codegen官方仓库复制Python控制器的模板文件（比如swagger-codegen/modules/swagger-codegen/src/main/resources/python/controller.mustache）。
• 修改模板，让生成的函数自动导入对应服务模块并调用方法，示例修改如下：

  def {{operationId}}({{#allParams}}{{paramName}}{{^last}}, {{/last}}{{/allParams}}):  # noqa: E501
      """{{summary}}
      {{#notes}}{{.}}{{/notes}}
      {{#allParams}}
      :param {{paramName}}: {{description}}
      :type {{paramName}}: {{dataType}}
      {{/allParams}}
      :rtype: {{returnType}}
      """
      {{#allParams}}{{#isBodyParam}}
      if connexion.request.is_json:
          {{paramName}} = {{dataType}}.from_dict(connexion.request.get_json())  # noqa: E501
      {{/isBodyParam}}{{/allParams}}
      # 新增：自动导入服务层并调用方法
      from swagger_server.services import {{classname}}_service
      return {{classname}}_service.{{operationId}}({{#allParams}}{{paramName}}{{^last}}, {{/last}}{{/allParams}})
  

• 使用--template-dir参数指定自定义模板路径重新生成存根：

  swagger-codegen generate -i petstore.yaml -l python -o ./petstore --template-dir ./custom-templates
  

这样每次生成的控制器都会自动转发到服务层，你只需在服务层维护自定义逻辑即可。

3. 利用Git版本管理合并变更 #

如果不慎在生成文件中编写了逻辑，可以用Git追踪差异并合并重新生成的代码：

• 先将修改后的生成文件提交到Git仓库。
• 重新生成存根文件。
• 使用git diff查看生成文件的变更，手动将自定义代码合并到新生成的文件中。
• 提交合并后的文件。

这种方法适合临时场景，但长期来看不如前两种方案可靠，容易因手动合并出错。

4. 谨慎使用--skip-overwrite参数 #

Swagger Codegen提供--skip-overwrite参数，会跳过已存在的文件，不覆盖它们。但该参数仅适用于确定生成文件不需要更新的场景：

• 如果YAML仅修改了文档描述，未变更接口参数、路径或响应结构，可以使用该参数：

  swagger-codegen generate -i petstore.yaml -l python -o ./petstore --skip-overwrite
  

• 注意：如果YAML修改了接口的参数、返回类型等核心定义，使用该参数会导致生成文件与API定义不一致，引发问题，因此不推荐常规使用。

内容的提问来源于stack exchange，提问作者Luca P.