如何实现OpenAPI Generator Python服务端存根增量生成工作流？

我刚好遇到过几乎一模一样的情况——用旧版openapi-generator生成Python服务端代码时，每次更新yaml规范都会把自定义的controller逻辑冲得一干二净，而且生成的代码都是函数式的，没法用面向对象的继承来隔离实现。下面是我亲测有效的几个方案：

方案1：手动拆分路由与实现（快速上手） #

这个方法不需要改生成器模板，适合临时快速解决问题：

• 第一步：保留生成的controller文件仅作为路由定义，绝对不要在里面写任何自定义业务逻辑。比如生成的users_controller.py里，自动生成的路由装饰器、函数签名和注释要保留，但函数体只做一件事：调用外部实现。
• 第二步：创建独立的实现文件，比如users_controller_impl.py，把所有你的业务逻辑放在这里：

  # users_controller_impl.py
  def get_users_impl():
      # 这里写你的实际逻辑：查询数据库、处理参数、构造响应
      return {"users": [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]}
  

• 第三步：修改生成的controller文件，导入并调用这个实现函数：

  # users_controller.py（生成后修改）
  from flask import request
  from .users_controller_impl import get_users_impl
  
  @api.route('/users', methods=['GET'])
  def get_users():
      """Get all users"""
      # noqa: E501
      return get_users_impl()
  

  下次更新yaml重新生成时，即使users_controller.py被覆盖，你只需要重新添加一行导入和函数调用就行——嫌麻烦的话，还可以把这个修改逻辑写成小脚本，生成后自动执行。

方案2：自定义生成器模板（一劳永逸） #

如果需要长期维护项目，自定义模板是最佳选择，让生成器自动生成指向外部实现的controller：

1. 从openapi-generator 3.3.4版本的源码里找到Python Flask的controller模板文件（路径大概是modules/openapi-generator/src/main/resources/python-flask/controller.mustache），复制到本地的custom-templates目录。
2. 修改这个controller.mustache模板，把默认的空实现替换成导入并调用外部函数的逻辑。比如原模板里的函数部分：

   def {{operationId}}():
       """{{summary}}"""
       # noqa: E501
       return 'do some magic!'
   

   改成：

   from {{packageName}}.{{classname}}_impl import {{operationId}}_impl
   
   def {{operationId}}():
       """{{summary}}"""
       # noqa: E501
       # 根据接口需求处理请求参数，比如request.args或request.json
       return {{operationId}}_impl(**request.args)
   

3. 生成代码时，用--template-dir参数指定你的自定义模板目录：

   openapi-generator generate -i your-spec.yaml -g python-flask -o ./generated --template-dir ./custom-templates
   

   这样每次生成的controller都会自动指向对应的*_impl.py文件，你只需要在这些实现文件里写逻辑，永远不会被覆盖，同时路由规则、参数校验等规范约束依然由生成的代码保证。

额外提醒 #

• 别浪费时间去修改生成文件里的注释（比如去掉# noqa: E501），生成器是直接替换整个文件的，根本不会检查这些注释内容。
• 如果规范新增了接口，生成后只需要在对应的*_impl.py文件里新增实现函数即可，完全遵循OpenAPI的约束要求。

内容的提问来源于stack exchange，提问作者Ionut Manolache