如果你的技术栈是 Python，自动生成 Swagger UI 文档的方案主要取决于你使用的 Web 框架。目前 Python 生态中最主流的两种方案分别是针对 FastAPI（原生支持，体验极佳）和 Flask（通过插件实现）的。

🚀 方案一：FastAPI（强烈推荐）

FastAPI 是 Python 现代 Web 框架中的佼佼者，它原生支持自动生成 OpenAPI（Swagger）文档。你只需要编写标准的 Python 类型提示代码，文档就会自动生成，无需任何额外配置。

1. 安装 FastAPI 和 Uvicorn

pip install fastapi uvicorn

2. 编写代码

FastAPI 利用 Python 的类型提示（Type Hints）和 Pydantic 模型来推断数据结构，自动生成文档。

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI(title="我的Python API", description="这是一个自动生成的接口文档示例")

# 定义数据模型
class Item(BaseModel):
    name: str
    price: float
    is_offer: bool = None

# 定义接口
@app.get("/")
def read_root():
    return {"Hello": "World"}

@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "q": q}

@app.post("/items/")
def create_item(item: Item):
    response_item = item.copy()
    response_item.price = item.price * 2
    return response_item

3. 运行并查看文档

启动服务：

uvicorn main:app --reload

访问以下地址即可看到交互式文档：

• Swagger UI: http://127.0.0.1:8000/docs (默认，支持在线调试)
• ReDoc: http://127.0.0.1:8000/redoc (另一种风格的静态文档)

优势： 零配置、实时更新、类型安全、自动校验数据。

🛠️ 方案二：Flask（使用插件）

Flask 本身不直接支持 Swagger，但可以通过第三方库轻松集成。最常用且简单的方案是使用 Autoswagger 或 Flasgger。

1. 使用 Autoswagger（极简方案）

如果你不想写复杂的注释，只想快速把接口展示出来，autoswagger 是个神器。它会自动扫描你的路由。

• 安装：

  pip install autoswagger
  

• 代码示例：

  from flask import Flask, request, jsonify
  from autoswagger import Autoswagger
  
  app = Flask(__name__)
  # 初始化 Autoswagger
  swagger = Autoswagger(app)
  
  @app.route('/hello', methods=['GET'])
  def hello():
      """
      这是一个简单的问候接口
      ---
      responses:
          200:
              description: 成功返回问候语
      """
      return jsonify({"message": "Hello World"})
  
  if __name__ == '__main__':
      app.run(debug=True)
  

• 访问： http://127.0.0.1:5000/swagger

2. 使用 Flasgger（更精细的控制）

如果你需要更详细的文档描述（如参数类型、具体响应模型），可以使用 flasgger。它通过解析函数文档字符串（docstring）中的 YAML 格式来生成文档。

• 安装：

  pip install flasgger
  

• 代码示例：

  from flask import Flask
  from flasgger import Swagger
  
  app = Flask(__name__)
  swagger = Swagger(app)
  
  @app.route('/user/<int:user_id>', methods=['GET'])
  def get_user(user_id):
      """
      获取用户信息
      这是一个用于演示 Flasgger 的接口
      ---
      parameters:
        - name: user_id
          in: path
          type: integer
          required: true
          description: 用户的唯一标识
      responses:
        200:
          description: 用户信息
          schema:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string
      """
      return {"id": user_id, "name": "Alice"}
  
  if __name__ == '__main__':
      app.run(debug=True)
  

• 访问： http://127.0.0.1:5000/apidocs/

📊 方案对比总结

建议： 如果你正在开启一个新项目，强烈建议使用 FastAPI，它能为你节省大量的文档编写和维护时间。