114 lines
2.7 KiB
Markdown
114 lines
2.7 KiB
Markdown
# 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 规范
|
||
|