Contoso Chat API文档自动生成：Swagger与FastAPI集成-优快云博客

Contoso Chat API文档自动生成：Swagger与FastAPI集成

【免费下载链接】contoso-chat 项目地址: https://gitcode.com/GitHub_Trending/co/contoso-chat

在现代API开发中，自动生成清晰易用的文档是提升开发效率和用户体验的关键环节。Contoso Chat项目基于FastAPI构建的后端服务，本指南将详细介绍如何为其API集成Swagger文档自动生成功能，帮助开发团队快速实现API文档的创建、维护与共享。

项目现状分析

Contoso Chat的API服务位于src/api/目录，核心入口文件为main.py。当前实现中，FastAPI基础架构已搭建完成，包含CORS中间件配置、追踪工具集成和基础路由定义，但尚未实现完整的API文档功能。

API架构概览

项目采用云原生架构设计，通过Azure容器应用(ACA)部署，其架构可参考docs/img/aca.png：

核心API端点包括根路由/和对话响应生成接口/api/create_response，后者接收用户问题、客户ID和对话历史参数，返回AI生成的响应结果。

集成Swagger文档的必要性

当前API开发面临三大痛点：

文档与代码不同步：手动编写的API文档难以实时反映代码变更
接口测试复杂：需要额外工具构造HTTP请求测试API
协作效率低：前端团队需反复沟通确认接口细节

FastAPI内置的Swagger UI和OpenAPI规范支持可完美解决这些问题，实现文档的自动生成与实时更新。

实施步骤

1. 安装依赖包

首先确认requirements.txt中已包含FastAPI标准依赖：

# API server
fastapi
fastapi[standard]

若缺失相关包，执行以下命令安装：

pip install fastapi[standard]

2. 配置Swagger文档元数据

修改main.py，在FastAPI实例化时添加文档配置参数：

app = FastAPI(
    title="Contoso Chat API",
    description="Contoso Chat应用的后端API服务，提供智能对话响应生成功能",
    version="1.0.0",
    terms_of_service="http://example.com/terms/",
    contact={
        "name": "Contoso Dev Team",
        "email": "dev@contoso.com",
    },
    license_info={
        "name": "MIT License",
        "url": "https://opensource.org/licenses/MIT",
    },
)

3. 添加接口文档注释

为API端点添加类型提示和文档字符串，以main.py中的/api/create_response接口为例：

from pydantic import BaseModel
from typing import Optional, List

class ChatRequest(BaseModel):
    """对话请求参数模型"""
    question: str
    """用户提出的问题"""
    customer_id: str
    """客户唯一标识符"""
    chat_history: Optional[str] = None
    """历史对话记录，JSON格式字符串"""

@app.post("/api/create_response", 
          summary="生成对话响应",
          description="接收用户问题和历史对话，返回AI生成的响应结果")
@trace
def create_response(request: ChatRequest) -> dict:
    """
    生成智能对话响应：
    
    - 根据customer_id获取客户上下文信息
    - 结合chat_history理解对话语境
    - 对question进行AI处理生成回答
    
    返回包含响应文本和相关元数据的JSON对象
    """
    result = get_response(request.customer_id, request.question, request.chat_history)
    return result

4. 访问Swagger UI文档

启动API服务后，通过以下URL访问自动生成的Swagger UI：

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

高级配置

自定义文档路径

如需修改默认文档URL路径，可在FastAPI初始化时配置：

app = FastAPI(
    docs_url="/api-docs",
    redoc_url="/redoc-docs",
    openapi_url="/openapi.json"
)

添加认证保护

为文档接口添加API密钥认证，保护文档不被未授权访问：

from fastapi import Security, Depends, HTTPException
from fastapi.security.api_key import APIKeyQuery, APIKeyCookie, APIKeyHeader, APIKey

API_KEY = "contoso_chat_secret_key"
API_KEY_NAME = "access_token"

api_key_query = APIKeyQuery(name=API_KEY_NAME, auto_error=False)

async def get_api_key(
    api_key_query: str = Security(api_key_query),
):
    if api_key_query == API_KEY:
        return api_key_query
    else:
        raise HTTPException(
            status_code=403, detail="Could not validate credentials"
        )

app = FastAPI(docs_url=None, redoc_url=None)  # 先禁用默认文档

@app.get("/docs", dependencies=[Depends(get_api_key)])
async def custom_swagger_ui_html():
    return get_swagger_ui_html(openapi_url="/openapi.json", title="Chat API Docs")

验证与测试

部署配置后，通过Swagger UI测试API接口的流程如下：

访问Swagger UI界面
找到/api/create_response接口
点击"Try it out"按钮
填写请求参数：

{
  "question": "这个产品的保修期是多久？",
  "customer_id": "CUST-001",
  "chat_history": "[]"
}

点击"Execute"发送请求
查看服务器响应结果

文档维护与扩展

版本控制

随着API迭代，应及时更新文档版本号，并在main.py中维护版本变更记录：

app = FastAPI(
    version="1.1.0",
    description="""
    Contoso Chat API v1.1.0更新：
    - 添加对话历史分页功能
    - 优化响应生成性能
    - 增加错误码详细说明
    """,
)

集成自动化测试

结合evaluate.py中的测试框架，可将Swagger文档与API测试自动化流程结合，确保文档示例与实际接口行为一致。

总结

通过FastAPI的Swagger集成，Contoso Chat项目实现了API文档的自动化生成，主要收益包括：

开发效率提升：文档自动更新，减少80%的文档维护工作量
测试便捷性：直接通过浏览器测试API，无需额外工具
协作质量改善：前后端团队基于统一文档协作，减少沟通成本

完整的实施细节可参考项目workshop文档，进一步的高级配置可查阅FastAPI官方文档。

提示：生产环境部署时，建议配合docs/workshop/docs/05-Deploy/中的部署指南，确保文档服务的安全访问与稳定运行。

【免费下载链接】contoso-chat 项目地址: https://gitcode.com/GitHub_Trending/co/contoso-chat

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考