docs(api): restore auth.md and update README/wiki links

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 分类" 表中重复。
This commit is contained in:
nullkey
2026-05-11 17:37:14 +08:00
committed by lyingbug
parent 1c7171b2c6
commit c8b2129853
3 changed files with 330 additions and 2 deletions
+12 -1
View File
@@ -3,6 +3,7 @@
## 目录
- [概述](#概述)
- [最权威参考:Swagger UI](#最权威参考swagger-ui)
- [基础信息](#基础信息)
- [认证机制](#认证机制)
- [错误处理](#错误处理)
@@ -12,6 +13,14 @@
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`
@@ -59,7 +68,7 @@ WeKnora API 按功能分为以下几类:
| 分类 | 描述 | 文档链接 |
|------|------|----------|
| 认证管理 | 用户注册、登录、令牌管理 | [OIDC认证调用流程.md](../OIDC认证调用流程.md) |
| 认证管理 | 用户注册、登录、令牌管理;OIDC 流程 | [auth.md](./auth.md) · [OIDC认证调用流程.md](../OIDC认证调用流程.md) |
| 租户管理 | 创建和管理租户账户 | [tenant.md](./tenant.md) |
| 知识库管理 | 创建、查询和管理知识库 | [knowledge-base.md](./knowledge-base.md) |
| 知识管理 | 上传、检索和管理知识内容 | [knowledge.md](./knowledge.md) |
@@ -80,3 +89,5 @@ WeKnora API 按功能分为以下几类:
| 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) |