Kamixitong/docs/FASTAPI.md

FastAPI接口配置文档

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

目录

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

简介

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

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

安装依赖

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

pip install fastapi uvicorn python-multipart

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

pip install -r requirements-fastapi.txt

启动FastAPI服务

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

python fastapi_app.py

默认情况下，服务将在以下地址运行：

• 地址: http://localhost:8000
• API文档: http://localhost:8000/docs
• ReDoc文档: http://localhost:8000/redoc

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

python fastapi_app.py --port 9000

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

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
• 请求体:

  {
    "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的唯一标识符
• 请求体:

  {
    "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
• 请求体:

  {
    "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密钥的唯一标识符
• 请求体:

  {
    "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
• 请求体:

  {
    "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版本的唯一标识符
• 请求体:

  {
    "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

# 获取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 -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

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. 如果遇到端口占用问题，可以修改启动命令中的端口号