Kamixitong/docs/FASTAPI.md

# FastAPI接口配置文档

本文档介绍了如何使用和配置KaMiXiTong系统的FastAPI接口，该接口提供了现代化的API和自动生成的交互式文档。

## 目录

1. [简介](#简介)
2. [安装依赖](#安装依赖)
3. [启动FastAPI服务](#启动fastapi服务)
4. [API接口说明](#api接口说明)
   - [API管理接口](#api管理接口)
   - [API密钥接口](#api密钥接口)
   - [API版本接口](#api版本接口)
5. [访问API文档](#访问api文档)
6. [调试示例](#调试示例)

## 简介

FastAPI接口是KaMiXiTong系统的一个补充接口，提供了以下优势：

- 自动生成交互式API文档
- 更快的接口响应速度
- 更好的数据验证和错误处理
- 支持异步操作
- 与现有Flask应用并行运行

## 安装依赖

在运行FastAPI接口之前，需要安装额外的依赖包：

```bash
pip install fastapi uvicorn python-multipart
```

或者使用requirements-fastapi.txt文件：

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

## 启动FastAPI服务

使用以下命令启动FastAPI服务：

```bash
python fastapi_app.py
```

默认情况下，服务将在以下地址运行：
- 地址: http://localhost:8000
- API文档: http://localhost:8000/docs
- ReDoc文档: http://localhost:8000/redoc

如果端口被占用，可以修改端口号：

```bash
python fastapi_app.py --port 9000
```

您也可以使用uvicorn直接启动：

```bash
uvicorn fastapi_app:app --host 127.0.0.1 --port 9000 --reload
```

## API接口说明

### API管理接口

#### 获取API列表
- **URL**: `GET /apis`
- **参数**:
  - `skip`: 跳过的记录数，默认为0
  - `limit`: 返回记录数，默认为100
- **响应**: API对象列表

#### 创建API
- **URL**: `POST /apis`
- **请求体**:
  ```json
  {
    "api_name": "示例API",
    "description": "这是一个示例API",
    "status": 1
  }
  ```
- **响应**: 创建的API对象

#### 获取API详情
- **URL**: `GET /apis/{api_id}`
- **参数**: `api_id` - API的唯一标识符
- **响应**: API对象

#### 更新API
- **URL**: `PUT /apis/{api_id}`
- **参数**: `api_id` - API的唯一标识符
- **请求体**:
  ```json
  {
    "api_name": "更新后的API名称",
    "description": "更新后的描述",
    "status": 1
  }
  ```
- **响应**: 更新后的API对象

#### 删除API
- **URL**: `DELETE /apis/{api_id}`
- **参数**: `api_id` - API的唯一标识符
- **响应**: 删除结果

### API密钥接口

#### 获取API密钥列表
- **URL**: `GET /api_keys`
- **参数**:
  - `skip`: 跳过的记录数，默认为0
  - `limit`: 返回记录数，默认为100
- **响应**: API密钥对象列表

#### 生成API密钥
- **URL**: `POST /api_keys`
- **请求体**:
  ```json
  {
    "name": "示例密钥",
    "api_id": "API_12345678",
    "description": "这是一个示例密钥",
    "status": 1,
    "expire_time": "2025-12-31T23:59:59"
  }
  ```
- **响应**: 创建的API密钥对象

#### 获取API密钥详情
- **URL**: `GET /api_keys/{key_id}`
- **参数**: `key_id` - API密钥的唯一标识符
- **响应**: API密钥对象

#### 更新API密钥
- **URL**: `PUT /api_keys/{key_id}`
- **参数**: `key_id` - API密钥的唯一标识符
- **请求体**:
  ```json
  {
    "name": "更新后的密钥名称",
    "api_id": "API_87654321",
    "description": "更新后的描述",
    "status": 1,
    "expire_time": "2026-12-31T23:59:59"
  }
  ```
- **响应**: 更新后的API密钥对象

#### 删除API密钥
- **URL**: `DELETE /api_keys/{key_id}`
- **参数**: `key_id` - API密钥的唯一标识符
- **响应**: 删除结果

### API版本接口

#### 获取API版本列表
- **URL**: `GET /api_versions`
- **参数**:
  - `skip`: 跳过的记录数，默认为0
  - `limit`: 返回记录数，默认为100
- **响应**: API版本对象列表

#### 创建API版本
- **URL**: `POST /api_versions`
- **请求体**:
  ```json
  {
    "version_num": "v1.0.0",
    "api_id": "API_12345678",
    "description": "初始版本",
    "publish_status": 1
  }
  ```
- **响应**: 创建的API版本对象

#### 获取API版本详情
- **URL**: `GET /api_versions/{version_id}`
- **参数**: `version_id` - API版本的唯一标识符
- **响应**: API版本对象

#### 更新API版本
- **URL**: `PUT /api_versions/{version_id}`
- **参数**: `version_id` - API版本的唯一标识符
- **请求体**:
  ```json
  {
    "version_num": "v1.0.1",
    "api_id": "API_12345678",
    "description": "修复了一些问题",
    "publish_status": 1
  }
  ```
- **响应**: 更新后的API版本对象

#### 删除API版本
- **URL**: `DELETE /api_versions/{version_id}`
- **参数**: `version_id` - API版本的唯一标识符
- **响应**: 删除结果

## 访问API文档

FastAPI提供了自动生成的交互式API文档：

1. **Swagger UI**: 访问 `http://localhost:9000/docs`
   - 提供交互式的API测试界面
   - 可以直接在浏览器中测试API接口
   - 显示详细的接口参数和响应格式

2. **ReDoc**: 访问 `http://localhost:9000/redoc`
   - 提供更简洁的API文档视图
   - 适合阅读和分享

## 调试示例

### 使用curl测试API

```bash
# 获取API列表
curl -X GET "http://localhost:9000/apis" -H "accept: application/json"

# 创建API
curl -X POST "http://localhost:9000/apis" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"api_name":"测试API","description":"用于测试的API","status":1}'

# 获取特定API
curl -X GET "http://localhost:9000/apis/API_12345678" -H "accept: application/json"
```

在Windows PowerShell中，可以使用以下命令：

```powershell
# 获取根路径信息
powershell -Command "Invoke-WebRequest -Uri 'http://127.0.0.1:9000/' -Method GET"

# 获取API列表
powershell -Command "Invoke-WebRequest -Uri 'http://127.0.0.1:9000/apis' -Method GET"
```

### 使用Python requests测试API

```python
import requests

# 基础URL
BASE_URL = "http://localhost:9000"

# 获取根路径信息
response = requests.get(f"{BASE_URL}/")
print("根路径信息:", response.json())

# 获取API列表
response = requests.get(f"{BASE_URL}/apis")
print("获取API列表:", response.json())

# 创建API
api_data = {
    "api_name": "测试API",
    "description": "用于测试的API",
    "status": 1
}
response = requests.post(f"{BASE_URL}/apis", json=api_data)
print("创建API:", response.json())

# 获取特定API
api_id = response.json()["api_id"]
response = requests.get(f"{BASE_URL}/apis/{api_id}")
print("获取API详情:", response.json())
```

### 在Swagger UI中测试

1. 打开浏览器访问 `http://localhost:9000/docs`
2. 展开相应的API接口
3. 点击"Try it out"按钮
4. 输入必要的参数
5. 点击"Execute"按钮执行请求
6. 查看响应结果

## 注意事项

1. FastAPI接口与Flask应用共享同一个数据库，因此数据是一致的
2. 两个应用可以同时运行，分别监听不同的端口
3. 建议在生产环境中使用反向代理（如Nginx）统一对外提供服务
4. 可以根据需要调整端口号和绑定地址
5. 如果遇到端口占用问题，可以修改启动命令中的端口号