mirror of
https://github.com/Tencent/WeKnora.git
synced 2026-06-04 13:30:32 +08:00
c8b2129853
Fixes #958. - 新建 docs/api/auth.md：覆盖 10 个 /auth/* 端点 register / login / oidc 三件套（config/url/callback）/ refresh / validate / logout / me / change-password。 说明各端点的鉴权方式（无 / refresh_token / Bearer JWT），并对齐 /auth/oidc/callback 的真实行为（始终 302 跳到 / 并把结果编码进 URL hash）。 - docs/api/README.md： - 增加"最权威参考：Swagger UI"段落，引导读者优先访问 /swagger/index.html（swagger 由 swag 注解自动从代码生成）。 - "认证管理"行链接由仅指向 OIDC 流程文档改为同时指向 auth.md 与 OIDC 流程文档。 - 新增 "IM 渠道" 行指向 docs/IM集成开发文档.md。 - 新增 "数据源导入" 行指向 docs/数据源导入开发文档.md。 - docs/wiki/API参考/API文档概览.md：随 api/README.md 的"认证管理" 行同步更新即可——IM 与数据源在该文件原有的"相关主题"/"反向链接" 小节已经登记，不在 "API 分类" 表中重复。
94 lines
4.0 KiB
Markdown
94 lines
4.0 KiB
Markdown
# WeKnora API 文档
|
||
|
||
## 目录
|
||
|
||
- [概述](#概述)
|
||
- [最权威参考：Swagger UI](#最权威参考swagger-ui)
|
||
- [基础信息](#基础信息)
|
||
- [认证机制](#认证机制)
|
||
- [错误处理](#错误处理)
|
||
- [API 概览](#api-概览)
|
||
|
||
## 概述
|
||
|
||
WeKnora 提供了一系列 RESTful API，用于创建和管理知识库、检索知识，以及进行基于知识的问答。本文档详细描述了这些 API 的使用方式。
|
||
|
||
## 最权威参考：Swagger UI
|
||
|
||
WeKnora 同时提供基于 OpenAPI 的 Swagger 文档。**启动服务后访问 `http://localhost:8080/swagger/index.html`**，可看到所有端点的完整参数、请求/响应 schema，并可直接在浏览器内试调——它随代码自动更新，是最准确的接口参考。
|
||
|
||
本目录下的 markdown 文档提供更易读的示例与场景说明，与 swagger 同步维护；当二者出现差异时，以 swagger 为准。
|
||
|
||
> Swagger UI 仅在非 release 模式（`GIN_MODE != release`）下挂载；生产部署默认关闭。
|
||
|
||
## 基础信息
|
||
|
||
- **基础 URL**: `/api/v1`
|
||
- **响应格式**: JSON
|
||
- **认证方式**: API Key
|
||
|
||
## 认证机制
|
||
|
||
所有 API 请求需要在 HTTP 请求头中包含 `X-API-Key` 进行身份认证：
|
||
|
||
```
|
||
X-API-Key: your_api_key
|
||
```
|
||
|
||
为便于问题追踪和调试，建议每个请求的 HTTP 请求头中添加 `X-Request-ID`：
|
||
|
||
```
|
||
X-Request-ID: unique_request_id
|
||
```
|
||
|
||
### 获取 API Key
|
||
|
||
在 web 页面完成账户注册后，请前往账户信息页面获取您的 API Key。
|
||
|
||
请妥善保管您的 API Key，避免泄露。API Key 代表您的账户身份，拥有完整的 API 访问权限。
|
||
|
||
## 错误处理
|
||
|
||
所有 API 使用标准的 HTTP 状态码表示请求状态，并返回统一的错误响应格式：
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"error": {
|
||
"code": "错误代码",
|
||
"message": "错误信息",
|
||
"details": "错误详情"
|
||
}
|
||
}
|
||
```
|
||
|
||
## API 概览
|
||
|
||
WeKnora API 按功能分为以下几类：
|
||
|
||
| 分类 | 描述 | 文档链接 |
|
||
|------|------|----------|
|
||
| 认证管理 | 用户注册、登录、令牌管理；OIDC 流程 | [auth.md](./auth.md) · [OIDC认证调用流程.md](../OIDC认证调用流程.md) |
|
||
| 租户管理 | 创建和管理租户账户 | [tenant.md](./tenant.md) |
|
||
| 知识库管理 | 创建、查询和管理知识库 | [knowledge-base.md](./knowledge-base.md) |
|
||
| 知识管理 | 上传、检索和管理知识内容 | [knowledge.md](./knowledge.md) |
|
||
| 模型管理 | 配置和管理各种AI模型 | [model.md](./model.md) |
|
||
| 分块管理 | 管理知识的分块内容 | [chunk.md](./chunk.md) |
|
||
| 标签管理 | 管理知识库的标签分类 | [tag.md](./tag.md) |
|
||
| FAQ管理 | 管理FAQ问答对 | [faq.md](./faq.md) |
|
||
| 智能体管理 | 创建和管理自定义智能体 | [agent.md](./agent.md) |
|
||
| 会话管理 | 创建和管理对话会话 | [session.md](./session.md) |
|
||
| 知识搜索 | 在知识库中搜索内容 | [knowledge-search.md](./knowledge-search.md) |
|
||
| 聊天功能 | 基于知识库和 Agent 进行问答 | [chat.md](./chat.md) |
|
||
| 消息管理 | 获取和管理对话消息 | [message.md](./message.md) |
|
||
| 评估功能 | 评估模型性能 | [evaluation.md](./evaluation.md) |
|
||
| 初始化管理 | 知识库模型配置与 Ollama 管理 | [initialization.md](./initialization.md) |
|
||
| 系统管理 | 系统信息、解析引擎、存储引擎 | [system.md](./system.md) |
|
||
| MCP 服务 | MCP 工具服务管理 | [mcp-service.md](./mcp-service.md) |
|
||
| 组织管理 | 组织、成员、知识库/智能体共享 | [organization.md](./organization.md) |
|
||
| Skills | 预装智能体技能 | [skill.md](./skill.md) |
|
||
| 网络搜索 | 网络搜索服务商 | [web-search.md](./web-search.md) |
|
||
| 向量存储 | 向量数据库连接管理 | [vector-store.md](./vector-store.md) |
|
||
| IM 渠道 | 企业微信 / 飞书 / Slack 等 IM 平台对接，含渠道 CRUD 与回调 | [../IM集成开发文档.md](../IM集成开发文档.md) |
|
||
| 数据源导入 | 飞书 / 企微 / Notion / Confluence 等外部数据源接入与同步 | [../数据源导入开发文档.md](../数据源导入开发文档.md) |
|