# DMS合规性测试工具 - FastAPI版本使用指南

## 概述

FastAPI版本提供了自动生成的交互式API文档，相比Flask版本具有以下优势：

- 🚀 **自动API文档**: 自动生成Swagger UI和ReDoc文档
- 📊 **数据验证**: 基于Pydantic的强类型数据验证
- ⚡ **高性能**: 基于Starlette和Uvicorn的异步框架
- 🔧 **类型提示**: 完整的类型提示支持
- 📝 **详细文档**: 丰富的API描述和示例

## 快速开始

### 1. 安装依赖

```bash
# 安装FastAPI版本的依赖
pip install -r requirements_fastapi.txt
```

### 2. 启动服务器

```bash
# 使用启动脚本（推荐）
./start_fastapi.sh

# 或直接运行
python3 fastapi_server.py

# 开发模式（自动重载）
python3 fastapi_server.py --reload

# 自定义配置
python3 fastapi_server.py --host 0.0.0.0 --port 8080 --workers 4
```

### 3. 访问API文档

启动后可以访问以下地址：

- **Swagger UI**: http://localhost:5050/docs
- **ReDoc**: http://localhost:5050/redoc
- **健康检查**: http://localhost:5050/

## API文档特性

### 自动生成的文档包含：

1. **完整的API规范**
   - 所有端点的详细描述
   - 请求/响应模型
   - 参数说明和示例

2. **交互式测试**
   - 直接在浏览器中测试API
   - 自动填充示例数据
   - 实时查看响应结果

3. **数据模型文档**
   - 详细的数据结构说明
   - 字段验证规则
   - 示例值

## 主要API端点

### 1. 健康检查
```
GET /
```
检查服务器状态和基本信息。

### 2. 服务信息
```
GET /info
```
获取详细的服务器信息和功能列表。

### 3. 执行测试
```
POST /run
```
执行API合规性测试的主要端点。

**请求体示例**:
```json
{
  "dms": "./assets/doc/dms/domain.json",
  "base_url": "https://api.example.com",
  "page_size": 1000,
  "strictness_level": "CRITICAL",
  "ignore_ssl": false,
  "generate_pdf": true,
  "verbose": false
}
```

**响应示例**:
```json
{
  "status": "completed",
  "message": "Tests finished.",
  "report_directory": "/path/to/reports/2024-01-15_10-30-45",
  "summary": {
    "endpoints_total": 150,
    "endpoints_passed": 145,
    "endpoints_failed": 5,
    "test_cases_total": 750
  },
  "pagination": {
    "page_size": 1000,
    "total_records": 150,
    "total_pages": 1,
    "pages_fetched": 1
  }
}
```

### 4. 报告管理
```
GET /reports          # 列出所有报告
GET /reports/{id}      # 下载特定报告
```

## 配置参数详解

### API定义源（三选一）
- `yapi`: YAPI定义文件路径
- `swagger`: Swagger/OpenAPI定义文件路径  
- `dms`: DMS服务发现的domain mapping文件路径

### 基本配置
- `base_url`: API基础URL（必填）
- `page_size`: DMS分页大小（1-10000，默认1000）
- `strictness_level`: 严格等级（CRITICAL/HIGH/MEDIUM/LOW）

### 过滤选项
- `categories`: YAPI分类列表
- `tags`: Swagger标签列表
- `ignore_ssl`: 忽略SSL证书验证

### LLM配置
- `llm_api_key`: LLM API密钥
- `llm_base_url`: LLM API基础URL
- `llm_model_name`: LLM模型名称
- `use_llm_for_*`: 各种LLM使用选项

## Docker部署

### 1. 构建镜像
```bash
docker build -f Dockerfile.fastapi -t dms-compliance-fastapi .
```

### 2. 使用Docker Compose
```bash
# 启动服务
docker-compose -f docker-compose.fastapi.yml up -d

# 查看日志
docker-compose -f docker-compose.fastapi.yml logs -f

# 停止服务
docker-compose -f docker-compose.fastapi.yml down
```

### 3. 环境变量
```bash
# 在docker-compose.yml中配置
environment:
  - HOST=0.0.0.0
  - PORT=5050
  - WORKERS=4
  - PYTHONUNBUFFERED=1
```

## 性能优化

### 1. 生产部署
```bash
# 使用多个工作进程
python3 fastapi_server.py --workers 4

# 使用Gunicorn（推荐生产环境）
gunicorn fastapi_server:app -w 4 -k uvicorn.workers.UvicornWorker
```

### 2. 内存优化
```bash
# 使用较小的分页大小
{
  "page_size": 500,  # 减少内存使用
  "dms": "..."
}
```

### 3. 并发处理
FastAPI天然支持异步处理，可以同时处理多个请求。

## 开发和调试

### 1. 开发模式
```bash
# 启用自动重载
python3 fastapi_server.py --reload

# 或使用环境变量
RELOAD=true ./start_fastapi.sh
```

### 2. 日志配置
```python
# 在代码中调整日志级别
logging.getLogger('ddms_compliance_suite').setLevel(logging.DEBUG)
```

### 3. 调试技巧
- 使用Swagger UI进行交互式测试
- 查看详细的错误信息和堆栈跟踪
- 利用Pydantic的数据验证错误信息

## 与Flask版本的对比

| 特性 | Flask版本 | FastAPI版本 |
|------|-----------|-------------|
| API文档 | 无 | 自动生成 |
| 数据验证 | 手动 | 自动（Pydantic） |
| 性能 | 中等 | 高（异步） |
| 类型提示 | 部分 | 完整 |
| 交互测试 | 无 | 内置 |
| 学习曲线 | 低 | 中等 |

## 故障排除

### 常见问题

1. **端口被占用**
   ```bash
   # 检查端口使用
   lsof -i :5050
   
   # 使用其他端口
   python3 fastapi_server.py --port 8080
   ```

2. **依赖缺失**
   ```bash
   # 重新安装依赖
   pip install -r requirements_fastapi.txt
   ```

3. **文档无法访问**
   - 检查服务器是否正常启动
   - 确认端口配置正确
   - 查看防火墙设置

### 调试命令
```bash
# 检查服务状态
curl http://localhost:5050/

# 查看服务信息
curl http://localhost:5050/info

# 测试API端点
curl -X POST http://localhost:5050/run \
  -H "Content-Type: application/json" \
  -d '{"dms": "./test.json", "base_url": "https://api.test.com"}'
```

## 最佳实践

1. **生产部署**
   - 使用多个工作进程
   - 配置反向代理（Nginx）
   - 启用HTTPS
   - 设置适当的超时时间

2. **安全考虑**
   - 限制CORS域名
   - 使用环境变量存储敏感信息
   - 定期更新依赖

3. **监控和日志**
   - 配置结构化日志
   - 监控API响应时间
   - 设置健康检查

4. **测试策略**
   - 使用小分页大小进行快速测试
   - 利用交互式文档进行手动测试
   - 编写自动化测试脚本