# Swagger API 文档说明

## 概述

项目已集成 Swagger 文档，可以通过浏览器访问交互式的 API 文档界面。

## 访问方式

启动服务后，在浏览器中访问：

**Swagger UI 文档地址**: `http://localhost:7500/api-docs`

## 功能特性

1. **交互式文档**：可以直接在浏览器中查看所有 API 接口的详细信息
2. **在线测试**：可以在文档页面直接测试 API 接口，无需使用 Postman 或其他工具
3. **参数说明**：详细的请求参数和响应格式说明
4. **错误码说明**：完整的错误码和错误信息说明

## 使用步骤

### 1. 安装依赖

确保已安装 `flasgger` 库：

```bash
pip install -r requirements.txt
```

### 2. 启动服务

```bash
python app.py
```

### 3. 访问文档

在浏览器中打开：`http://localhost:7500/api-docs`

## 接口文档内容

### AI解析接口

- **路径**: `/api/ai/extract`
- **方法**: POST
- **功能**: 从输入数据中提取结构化字段
- **参数说明**:
  - `businessType`: 业务类型（必填）
  - `inputData`: 输入数据列表（必填）
    - `fieldCode`: 字段编码
    - `fieldValue`: 字段值（原始文本）

### 字段配置接口

- **路径**: `/api/fields`
- **方法**: GET
- **功能**: 获取字段配置
- **参数说明**:
  - `businessType`: 业务类型（可选，默认：INVESTIGATION）

## 在 Swagger UI 中测试接口

1. 打开 Swagger 文档页面
2. 找到要测试的接口（如 `/api/ai/extract`）
3. 点击 "Try it out" 按钮
4. 填写请求参数
5. 点击 "Execute" 执行请求
6. 查看响应结果

## 示例

### 测试 AI 解析接口

在 Swagger UI 中，找到 `/api/ai/extract` 接口：

1. 点击 "Try it out"
2. 在请求体中填入：
```json
{
  "businessType": "INVESTIGATION",
  "inputData": [
    {
      "fieldCode": "clue_info",
      "fieldValue": "被举报用户名称是张三，年龄30岁，某公司总经理"
    },
    {
      "fieldCode": "target_basic_info_clue",
      "fieldValue": "张三，男，汉族，1980年5月出生，山西太原人，本科学历，2000年参加工作，2005年加入中国共产党。"
    }
  ]
}
```
3. 点击 "Execute"
4. 查看响应结果

## 注意事项

1. **服务必须运行**：访问 Swagger 文档前，确保服务已启动
2. **跨域问题**：如果遇到跨域问题，确保已配置 CORS
3. **API 密钥**：测试 AI 解析接口时，确保已配置 `SILICONFLOW_API_KEY` 环境变量

## 相关链接

- **测试页面**: http://localhost:7500/
- **Swagger 文档**: http://localhost:7500/api-docs
- **API 规范 JSON**: http://localhost:7500/apispec.json

## 技术实现

- 使用 `flasgger` 库集成 Swagger
- 通过函数文档字符串（docstring）自动生成 API 文档
- 支持 OpenAPI 2.0 规范