如何为vanilla Python编写、部署至AWS Lambda的API自动生成Swagger文档

FastAPI、Django Rest-framework这类框架的自动文档能力没有黑科技，本质逻辑是统一的：

• 自动从路由配置中抓取接口路径、允许的请求方法
• 从参数校验规则（比如FastAPI的Pydantic模型、DRF的序列化器）中提取请求/响应的字段结构、数据类型、必填规则、校验约束
• 从视图函数/类的注释、装饰器参数中读取接口描述、错误码、分类标签等补充信息
• 把上述所有信息按照OpenAPI规范（Swagger是OpenAPI规范的旧称）拼接成标准的JSON/YAML配置文件
• 内置静态文件服务能力，把Swagger UI的静态页面和生成的OpenAPI配置绑定，直接对外提供可交互的文档页面

原生Python编写的Lambda API大多对接AWS API Gateway触发，目前有三类成熟方案可以实现接近零成本的自动Swagger文档生成，不需要大规模重构现有业务代码：

方案1：轻量无侵入的apispec+自定义装饰器方案 #

这个方案适配任意原生Python接口，侵入性最低，只需要给接口加装饰器标注即可：

• 先安装依赖：pip install apispec PyYAML marshmallow
• 自定义一个极简装饰器，给每个Lambda接口处理函数标注路径、请求方法、请求/响应模型、描述信息
• 打包部署前运行一次生成脚本，自动遍历所有接口生成标准OpenAPI配置
• 生成的配置可以直接导入AWS API Gateway生成官方文档，也可以和Swagger UI静态文件绑定后部署到S3提供可交互页面

示例代码参考：

from apispec import APISpec
from apispec.ext.marshmallow import MarshmallowPlugin
from marshmallow import Schema, fields

# 初始化OpenAPI配置实例
spec = APISpec(
    title="Lambda API文档",
    version="1.0.0",
    openapi_version="3.0.2",
    plugins=[MarshmallowPlugin()],
)

# 自定义接口文档装饰器
def api_doc(path, method, request_schema=None, response_schema=None, description=""):
    def wrapper(func):
        spec.path(
            path=path,
            operations={
                method.lower(): {
                    "description": description,
                    "requestBody": {"content": {"application/json": {"schema": request_schema}}} if request_schema else None,
                    "responses": {"200": {"content": {"application/json": {"schema": response_schema}}}}
                }
            }
        )
        return func
    return wrapper

# 定义参数/响应模型
class UserSchema(Schema):
    id = fields.Int(required=True)
    name = fields.Str(required=True)

# 业务接口示例，仅加装饰器无需修改原有逻辑
@api_doc(
    path="/users",
    method="GET",
    description="获取用户列表",
    response_schema=UserSchema(many=True)
)
def list_users_handler(event, context):
    # 原有业务逻辑不变
    return {
        "statusCode": 200,
        "body": '[{"id":1, "name":"张三"}]'
    }

# 生成OpenAPI配置文件
if __name__ == "__main__":
    with open("openapi.yaml", "w", encoding="utf-8") as f:
        f.write(spec.to_yaml())

方案2：FastAPI+mangum兼容方案 #

如果可以接受引入轻量Web框架，这个方案可以完全复用FastAPI的开箱即用文档能力，不需要自己维护配置生成逻辑：

• 安装依赖：pip install fastapi mangum
• 把现有Lambda处理逻辑注册成FastAPI的路由，最后用mangum把FastAPI应用转成Lambda兼容的Handler
• 部署后直接就能访问FastAPI自带的Swagger UI页面，不需要额外配置

方案3：基础设施即代码绑定方案 #

如果你用AWS SAM或者CDK做部署，可以在定义API Gateway资源的时候直接关联Lambda函数和接口的OpenAPI配置，部署时AWS会自动生成官方API文档，不需要引入任何业务侧第三方依赖。

• 不存在完全不需要标注就能自动生成准确文档的工具，FastAPI的零成本体验本质是它把参数校验和文档信息收集做了绑定，你写参数校验逻辑的时候已经同步提供了文档需要的所有信息
• 生成的OpenAPI配置可以直接导入Postman、API Gateway等工具使用，不需要单独部署Swagger UI也能满足接口调试需求

内容的提问来源于stack exchange，提问作者Jeet Patel