在 Azure Functions 中集成 Swagger 和 ReDoc：构建优雅的 API 文档

最新推荐文章于 2025-12-21 02:09:50 发布

原创最新推荐文章于 2025-12-21 02:09:50 发布 · 546 阅读

6 ·

CC 4.0 BY-SA版权

文章标签：

#azure #python

在现代应用开发中，API 文档是开发者与外部用户交流的桥梁。为了给 Azure Functions 提供完善的 API 文档支持，本文将介绍如何通过 FastAPI 集成 Swagger 和 ReDoc，以实现交互式的 API 文档和美观的文档界面。

为什么选择 Swagger 和 ReDoc？

Swagger

特点：
- 提供交互式文档，开发者可以直接测试 API。
- 是 OpenAPI 规范的核心工具，广泛使用。
适用场景：
- 开发阶段，方便调试和测试 API。

ReDoc

特点：
- 专注于生成美观、简洁的文档。
- 提供响应式设计，适合终端用户和外部集成。
适用场景：
- 展示阶段，为外部用户提供友好的文档界面。

目标

在 Azure Functions 中集成：

Swagger UI：交互式 API 文档。
ReDoc：简洁美观的文档界面。

最终文档访问地址：

Swagger UI：/api/swagger-ui
ReDoc：/api/redoc
OpenAPI JSON：/api/docs

步骤 1：准备工作

创建 Azure Functions 项目

如果你还没有 Azure Functions 项目，使用以下命令初始化一个 Python 项目：

func init my-functions --python
cd my-functions
func new --name MyFunction --template "HTTP trigger"

安装依赖
在项目中添加以下依赖：

pip install fastapi python-worker-extension-timer

将这些依赖写入 requirements.txt：

fastapi
python-worker-extension-timer
azure-functions

步骤 2：代码实现

在项目中修改主文件（例如 function.py），实现 Swagger 和 ReDoc 的集成。

完整代码
以下是完整实现代码：

from fastapi import FastAPI
from python_worker_extension_timer import TimerExtension
import os
import json
from fastapi.openapi.utils import get_openapi
from azure.functions import HttpRequest, HttpResponse
from azure.functions import FunctionApp, AuthLevel
from fastapi.openapi.docs import get_swagger_ui_html, get_redoc_html

# 配置 Timer 扩展
use_timer = os.environ.get("UseTimer", "false")
if use_timer == "true":
    TimerExtension.configure(append_to_http_response=True)
else:
    TimerExtension.configure(append_to_http_response=False)

# 实例化 FastAPI 应用
fastapi_app = FastAPI(
    title="Azure Functions API with Swagger and ReDoc",
    version="1.0.0",
    description="API documentation for Azure Functions"
)

# 创建 FunctionApp 实例
app = FunctionApp(http_auth_level=AuthLevel.ANONYMOUS)

# 注册蓝图（可选）
from controller.auth_controller import bp as auth_bp
from controller.user_controller import bp as user_bp
app.register_functions(auth_bp)
app.register_functions(user_bp)

# OpenAPI JSON 文档
@app.function_name(name="swagger_docs")
@app.route(route="docs", auth_level=AuthLevel.ANONYMOUS)
def swagger_docs(req: HttpRequest) -> HttpResponse:
    openapi_schema = get_openapi(
        title=fastapi_app.title,
        version=fastapi_app.version,
        description=fastapi_app.description,
        routes=fastapi_app.routes,
    )
    return HttpResponse(
        body=json.dumps(openapi_schema, indent=4),
        mimetype="application/json"
    )

# Swagger UI 路由
@app.function_name(name="swagger_ui")
@app.route(route="swagger-ui", auth_level=AuthLevel.ANONYMOUS)
def swagger_ui(req: HttpRequest) -> HttpResponse:
    html_content = get_swagger_ui_html(
        openapi_url="/api/docs",
        title="Swagger UI - Azure Functions API",
    ).body.decode("utf-8")
    return HttpResponse(body=html_content, mimetype="text/html")

# ReDoc 路由
@app.function_name(name="redoc_ui")
@app.route(route="redoc", auth_level=AuthLevel.ANONYMOUS)
def redoc_ui(req: HttpRequest) -> HttpResponse:
    html_content = get_redoc_html(
        openapi_url="/api/docs",
        title="ReDoc - Azure Functions API",
        redoc_js_url="https://cdn.jsdelivr.net/npm/redoc@2.0.0/bundles/redoc.standalone.js",
        with_google_fonts=True
    ).body.decode("utf-8")
    return HttpResponse(body=html_content, mimetype="text/html")