759 lines
36 KiB
Markdown
759 lines
36 KiB
Markdown
# API Portal — 睿核科技 API 文档门户 设计文档
|
||
|
||
> 日期：2026-06-08
|
||
> 状态：待审核
|
||
> 作者：AI + 张晟
|
||
|
||
---
|
||
|
||
## 一、项目概述
|
||
|
||
### 1.1 项目名称
|
||
|
||
- **前端项目**：`api-portal`（睿核科技 API 文档门户）
|
||
- **后端服务**：`rui-service-apidoc`（API 文档管理微服务）
|
||
|
||
### 1.2 核心目标
|
||
|
||
构建一个**精美的 API 文档门户系统**，具备以下能力：
|
||
|
||
1. **多源 API 文档聚合** — 自动同步微服务 OpenAPI JSON + 手动导入
|
||
2. **自定义多级菜单** — 3 级菜单树，自由组织，不受 Controller 结构限制
|
||
3. **文档补全增强** — 管理后台补充中文说明、示例、注意事项
|
||
4. **精美文档展示** — VitePress 风格三栏布局，代码高亮
|
||
5. **AI 结构化接口** — 提供完整 API 信息供 AI 读取、代码生成、变更感知
|
||
6. **多项目管理** — 可自由创建项目，每个项目独立菜单和文档
|
||
|
||
### 1.3 用户角色
|
||
|
||
| 角色 | 说明 |
|
||
|------|------|
|
||
| 匿名访客 | 浏览公开项目的 API 文档 |
|
||
| 开发者 | 浏览 + 搜索 + 测试 API |
|
||
| 管理员 | 管理项目、菜单、同步 API、补全文档 |
|
||
| AI Agent | 通过专用接口读取结构化 API 数据 |
|
||
|
||
---
|
||
|
||
## 二、系统架构
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────────┐
|
||
│ 整体架构 │
|
||
├──────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ 微服务集群 │
|
||
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
|
||
│ │ rui-user │ │rui-system │ │rui-cashier│ │rui-payment│ │
|
||
│ │/v3/api- │ │/v3/api- │ │/v3/api- │ │/v3/api- │ │
|
||
│ │ docs │ │ docs │ │ docs │ │ docs │ │
|
||
│ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ │
|
||
│ │ │ │ │ │
|
||
│ ▼ ▼ ▼ ▼ │
|
||
│ ┌──────────────────────────────────────────────────────┐ │
|
||
│ │ rui-service-apidoc（独立微服务） │ │
|
||
│ │ │ │
|
||
│ │ 同步引擎 文档管理 AI 接口 │ │
|
||
│ │ - 定时拉取 - 菜单 CRUD - 结构化查询 │ │
|
||
│ │ - 手动触发 - 文档补全 - 变更检测 │ │
|
||
│ │ - JSON 导入 - 版本管理 - 代码生成数据 │ │
|
||
│ └──────────┬───────────────────┬───────────────────────┘ │
|
||
│ │ │ │
|
||
│ ┌────────▼────────┐ ┌──────▼──────────┐ │
|
||
│ │ admin-ui │ │ api-portal │ │
|
||
│ │ (管理后台) │ │ (文档门户) │ │
|
||
│ │ 补全信息/管理菜单 │ │ 精美展示/公开 │ │
|
||
│ └─────────────────┘ └─────────────────┘ │
|
||
│ │
|
||
│ ┌────────────────────────────────────────┐ │
|
||
│ │ AI Agent (Codex 等) │ │
|
||
│ │ 通过 /ai/* 接口读取结构化 API 数据 │ │
|
||
│ └────────────────────────────────────────┘ │
|
||
└──────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 三、后端设计 — rui-apidoc
|
||
|
||
### 3.1 技术栈
|
||
|
||
| 项目 | 选型 | 说明 |
|
||
|------|------|------|
|
||
| 语言 | Java 21 | 和框架一致 |
|
||
| 框架 | Spring Boot 3 + Spring Cloud | 和框架一致 |
|
||
| 数据库 | MySQL 8 | 和框架一致 |
|
||
| ORM | MyBatis-Plus | 继承 BaseEntity |
|
||
| API 文档 | SpringDoc (OpenAPI 3) | 和框架一致 |
|
||
| 注册中心 | Nacos | 复用现有 |
|
||
| 包管理 | Maven | parent: rui-parent |
|
||
|
||
### 3.2 模块结构
|
||
|
||
遵循 `业务应用模块创建规则`，作为 `app/` 下的独立业务模块：
|
||
|
||
```
|
||
app/
|
||
└── rui-apidoc/
|
||
├── pom.xml # parent: rui-app
|
||
├── rui-apidoc-api/ # [可部署] REST API + 启动类
|
||
│ └── src/main/java/com/rui/apidoc/api/
|
||
│ ├── ApidocApplication.java
|
||
│ └── controller/
|
||
│ ├── PortalController.java # 文档门户 API（公开）
|
||
│ ├── ApidocController.java # 管理后台 API（需认证）
|
||
│ └── AiController.java # AI 专用 API
|
||
├── rui-apidoc-common/ # [库] DTO、VO、枚举
|
||
│ └── src/main/java/com/rui/apidoc/
|
||
│ ├── dto/
|
||
│ ├── vo/
|
||
│ └── enums/
|
||
├── rui-apidoc-core/ # [库] Entity、Mapper、Service
|
||
│ └── src/main/java/com/rui/apidoc/core/
|
||
│ ├── entity/
|
||
│ ├── mapper/
|
||
│ ├── service/
|
||
│ └── config/
|
||
└── rui-apidoc-task/ # [库] 定时同步任务
|
||
└── src/main/java/com/rui/apidoc/task/
|
||
└── SyncTask.java
|
||
```
|
||
|
||
**POM 层级**：
|
||
```
|
||
app/pom.xml (rui-app)
|
||
└── rui-apidoc/pom.xml (parent: rui-app)
|
||
├── rui-apidoc-api → parent: rui-apidoc
|
||
├── rui-apidoc-common
|
||
├── rui-apidoc-core
|
||
└── rui-apidoc-task
|
||
```
|
||
|
||
**依赖关系**：
|
||
```
|
||
common → rui-common-core
|
||
core → rui-common-mybatis, rui-common-security, common
|
||
task → core, common
|
||
api → core, task, rui-common-security, rui-common-web
|
||
```
|
||
|
||
### 3.3 核心数据模型
|
||
|
||
> 所有实体继承 `BaseEntity`，自动包含 id, tenant_id, deleted, created_by, created_at, updated_by, updated_at 字段。
|
||
> 建表 SQL 只写业务字段，公共字段由 BaseEntity 规范统一。
|
||
|
||
#### 3.3.1 项目表 `apidoc_project`
|
||
|
||
```sql
|
||
CREATE TABLE apidoc_project (
|
||
-- 业务字段
|
||
project_key VARCHAR(64) NOT NULL COMMENT '项目唯一标识，如 rui-framework',
|
||
name VARCHAR(128) NOT NULL COMMENT '项目名称',
|
||
description TEXT DEFAULT NULL COMMENT '项目描述',
|
||
visibility TINYINT NOT NULL DEFAULT 0 COMMENT '可见性 0=公开 1=需登录 2=仅管理员',
|
||
logo_url VARCHAR(512) DEFAULT NULL COMMENT '项目 Logo',
|
||
sort_order INT NOT NULL DEFAULT 0 COMMENT '排序',
|
||
-- BaseEntity 公共字段
|
||
id BIGINT NOT NULL COMMENT '主键ID（雪花算法）',
|
||
tenant_id BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID',
|
||
deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除 0=正常 1=已删',
|
||
created_by BIGINT DEFAULT NULL COMMENT '创建者ID',
|
||
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
|
||
updated_by BIGINT DEFAULT NULL COMMENT '更新者ID',
|
||
updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
|
||
PRIMARY KEY (id),
|
||
UNIQUE KEY uk_project_key (project_key)
|
||
) COMMENT='API文档项目';
|
||
```
|
||
|
||
#### 3.3.2 微服务注册表 `apidoc_service`
|
||
|
||
```sql
|
||
CREATE TABLE apidoc_service (
|
||
-- 业务字段
|
||
project_id BIGINT NOT NULL COMMENT '所属项目ID',
|
||
service_name VARCHAR(128) NOT NULL COMMENT '服务名，如 rui-service-user',
|
||
service_url VARCHAR(512) DEFAULT NULL COMMENT '服务地址，如 http://rui-service-user:8080',
|
||
sync_mode TINYINT NOT NULL DEFAULT 0 COMMENT '同步模式 0=自动同步(URL) 1=手动导入',
|
||
sync_status TINYINT NOT NULL DEFAULT 0 COMMENT '同步状态 0=未同步 1=同步中 2=成功 3=失败',
|
||
last_sync_at DATETIME DEFAULT NULL COMMENT '最后同步时间',
|
||
openapi_json MEDIUMTEXT DEFAULT NULL COMMENT '缓存的 OpenAPI JSON',
|
||
-- BaseEntity 公共字段
|
||
id BIGINT NOT NULL COMMENT '主键ID（雪花算法）',
|
||
tenant_id BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID',
|
||
deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除',
|
||
created_by BIGINT DEFAULT NULL,
|
||
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||
updated_by BIGINT DEFAULT NULL,
|
||
updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||
PRIMARY KEY (id),
|
||
INDEX idx_project (project_id)
|
||
) COMMENT='API文档微服务注册';
|
||
```
|
||
|
||
#### 3.3.3 多级菜单表 `apidoc_menu`
|
||
|
||
```sql
|
||
CREATE TABLE apidoc_menu (
|
||
-- 业务字段
|
||
project_id BIGINT NOT NULL COMMENT '所属项目ID',
|
||
parent_id BIGINT NOT NULL DEFAULT 0 COMMENT '父级菜单ID，0=顶级',
|
||
name VARCHAR(128) NOT NULL COMMENT '菜单名称',
|
||
icon VARCHAR(64) DEFAULT NULL COMMENT '图标',
|
||
menu_type TINYINT NOT NULL DEFAULT 0 COMMENT '类型 0=目录 1=自定义内容页 2=接口组',
|
||
sort_order INT NOT NULL DEFAULT 0 COMMENT '同级排序',
|
||
service_id BIGINT DEFAULT NULL COMMENT '关联的微服务(menu_type=2时)',
|
||
endpoint_paths JSON DEFAULT NULL COMMENT '关联的API路径列表',
|
||
content MEDIUMTEXT DEFAULT NULL COMMENT 'Markdown自定义内容(menu_type=1时)',
|
||
-- BaseEntity 公共字段
|
||
id BIGINT NOT NULL COMMENT '主键ID（雪花算法）',
|
||
tenant_id BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID',
|
||
deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除',
|
||
created_by BIGINT DEFAULT NULL,
|
||
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||
updated_by BIGINT DEFAULT NULL,
|
||
updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||
PRIMARY KEY (id),
|
||
INDEX idx_project_parent (project_id, parent_id)
|
||
) COMMENT='API文档菜单';
|
||
```
|
||
|
||
#### 3.3.4 API 端点表 `apidoc_endpoint`
|
||
|
||
```sql
|
||
CREATE TABLE apidoc_endpoint (
|
||
-- 业务字段
|
||
service_id BIGINT NOT NULL COMMENT '所属微服务ID',
|
||
menu_id BIGINT DEFAULT NULL COMMENT '关联菜单ID',
|
||
method VARCHAR(10) NOT NULL COMMENT 'HTTP方法 GET/POST/PUT/DELETE/PATCH',
|
||
path VARCHAR(512) NOT NULL COMMENT '接口路径',
|
||
summary VARCHAR(256) DEFAULT NULL COMMENT '接口摘要(来自OpenAPI)',
|
||
description TEXT DEFAULT NULL COMMENT '接口描述(来自OpenAPI)',
|
||
deprecated TINYINT NOT NULL DEFAULT 0 COMMENT '是否废弃',
|
||
tags JSON DEFAULT NULL COMMENT 'OpenAPI tags',
|
||
request_params JSON DEFAULT NULL COMMENT '查询参数 [{name,type,required,description}]',
|
||
request_body JSON DEFAULT NULL COMMENT '请求体 JSON Schema',
|
||
request_headers JSON DEFAULT NULL COMMENT '请求头',
|
||
path_params JSON DEFAULT NULL COMMENT '路径参数',
|
||
response_200 JSON DEFAULT NULL COMMENT '200 响应 JSON Schema',
|
||
response_error JSON DEFAULT NULL COMMENT '错误响应 Schema',
|
||
raw_openapi JSON DEFAULT NULL COMMENT '原始 OpenAPI operation 对象',
|
||
content_hash VARCHAR(64) DEFAULT NULL COMMENT '内容哈希，用于变更检测',
|
||
-- BaseEntity 公共字段
|
||
id BIGINT NOT NULL COMMENT '主键ID（雪花算法）',
|
||
tenant_id BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID',
|
||
deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除',
|
||
created_by BIGINT DEFAULT NULL,
|
||
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||
updated_by BIGINT DEFAULT NULL,
|
||
updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||
PRIMARY KEY (id),
|
||
UNIQUE KEY uk_service_method_path (service_id, method, path),
|
||
INDEX idx_service (service_id),
|
||
INDEX idx_menu (menu_id)
|
||
) COMMENT='API端点';
|
||
```
|
||
|
||
#### 3.3.5 文档补充表 `apidoc_extra`
|
||
|
||
```sql
|
||
CREATE TABLE apidoc_extra (
|
||
-- 业务字段
|
||
endpoint_id BIGINT NOT NULL COMMENT '关联端点ID',
|
||
custom_title VARCHAR(256) DEFAULT NULL COMMENT '自定义标题(覆盖summary)',
|
||
custom_desc TEXT DEFAULT NULL COMMENT '自定义说明(中文描述)',
|
||
use_cases TEXT DEFAULT NULL COMMENT '使用场景说明',
|
||
notes TEXT DEFAULT NULL COMMENT '注意事项',
|
||
request_example JSON DEFAULT NULL COMMENT '请求示例',
|
||
response_example JSON DEFAULT NULL COMMENT '响应示例',
|
||
error_example JSON DEFAULT NULL COMMENT '错误响应示例',
|
||
test_cases JSON DEFAULT NULL COMMENT '测试用例 [{name,params,expected}]',
|
||
-- BaseEntity 公共字段
|
||
id BIGINT NOT NULL COMMENT '主键ID（雪花算法）',
|
||
tenant_id BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID',
|
||
deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除',
|
||
created_by BIGINT DEFAULT NULL,
|
||
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||
updated_by BIGINT DEFAULT NULL,
|
||
updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||
PRIMARY KEY (id),
|
||
UNIQUE KEY uk_endpoint (endpoint_id)
|
||
) COMMENT='API文档补充信息';
|
||
```
|
||
|
||
#### 3.3.6 版本快照表 `apidoc_version`
|
||
|
||
```sql
|
||
CREATE TABLE apidoc_version (
|
||
-- 业务字段
|
||
service_id BIGINT NOT NULL COMMENT '所属微服务ID',
|
||
version VARCHAR(32) NOT NULL COMMENT '版本号，如 v1.2.0',
|
||
openapi_json MEDIUMTEXT DEFAULT NULL COMMENT 'OpenAPI JSON 快照',
|
||
change_log TEXT DEFAULT NULL COMMENT '变更日志(Markdown)',
|
||
-- BaseEntity 公共字段
|
||
id BIGINT NOT NULL COMMENT '主键ID（雪花算法）',
|
||
tenant_id BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID',
|
||
deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除',
|
||
created_by BIGINT DEFAULT NULL,
|
||
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||
updated_by BIGINT DEFAULT NULL,
|
||
updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||
PRIMARY KEY (id),
|
||
INDEX idx_service (service_id)
|
||
) COMMENT='API文档版本快照';
|
||
```
|
||
|
||
### 3.4 核心 API 设计
|
||
|
||
> 所有接口统一使用 `Result<T>` 返回封装（error=0 成功，code 为业务编码，message 提示，data 业务数据）。
|
||
> Controller 路径遵循 `/{模块}/{功能}/{方法}` 规范。
|
||
|
||
#### 3.4.1 文档门户 API（公开，免认证）
|
||
|
||
| 方法 | 路径 | 返回类型 | 说明 |
|
||
|------|------|---------|------|
|
||
| GET | `/apidoc/portal/project/list` | `Result<List<ProjectVO>>` | 公开项目列表 |
|
||
| GET | `/apidoc/portal/project/{key}` | `Result<ProjectVO>` | 项目详情 |
|
||
| GET | `/apidoc/portal/project/{key}/menu` | `Result<List<MenuTreeVO>>` | 项目菜单树 |
|
||
| GET | `/apidoc/portal/project/{key}/menu/{menuId}` | `Result<MenuDetailVO>` | 菜单详情 |
|
||
| GET | `/apidoc/portal/endpoint/{id}` | `Result<EndpointDetailVO>` | 端点详情(含补充信息) |
|
||
| GET | `/apidoc/portal/search` | `Result<List<EndpointVO>>` | 全文搜索 |
|
||
|
||
#### 3.4.2 管理后台 API（需认证 + 管理员权限）
|
||
|
||
遵循 Controller 分类规范，管理接口使用 `ApidocController`：
|
||
|
||
| 方法 | 路径 | 返回类型 | 说明 |
|
||
|------|------|---------|------|
|
||
| POST | `/apidoc/admin/project` | `Result<Long>` | 创建项目 |
|
||
| PUT | `/apidoc/admin/project/{id}` | `Result<Void>` | 更新项目 |
|
||
| DELETE | `/apidoc/admin/project/{id}` | `Result<Void>` | 删除项目 |
|
||
| POST | `/apidoc/admin/service` | `Result<Long>` | 注册微服务 |
|
||
| POST | `/apidoc/admin/service/{id}/sync` | `Result<Void>` | 手动触发同步 |
|
||
| POST | `/apidoc/admin/service/{id}/import` | `Result<Void>` | 手动导入 OpenAPI JSON |
|
||
| POST | `/apidoc/admin/menu` | `Result<Long>` | 创建菜单 |
|
||
| PUT | `/apidoc/admin/menu/{id}` | `Result<Void>` | 更新菜单 |
|
||
| DELETE | `/apidoc/admin/menu/{id}` | `Result<Void>` | 删除菜单 |
|
||
| PUT | `/apidoc/admin/menu/sort` | `Result<Void>` | 批量排序 |
|
||
| POST | `/apidoc/admin/menu/{id}/bind` | `Result<Void>` | 菜单绑定 API 端点 |
|
||
| PUT | `/apidoc/admin/extra/{endpointId}` | `Result<Void>` | 更新补充信息 |
|
||
| POST | `/apidoc/admin/service/{id}/snapshot` | `Result<Void>` | 创建版本快照 |
|
||
|
||
#### 3.4.3 AI 专用 API
|
||
|
||
| 方法 | 路径 | 返回类型 | 说明 |
|
||
|------|------|---------|------|
|
||
| GET | `/apidoc/ai/projects` | `Result<List<AiProjectVO>>` | 所有项目(含服务概况) |
|
||
| GET | `/apidoc/ai/project/{key}/endpoints` | `Result<List<AiEndpointVO>>` | 项目全部端点(完整结构化) |
|
||
| GET | `/apidoc/ai/endpoint/{id}` | `Result<AiEndpointDetailVO>` | 单个端点完整信息 |
|
||
| GET | `/apidoc/ai/endpoint/search` | `Result<List<AiEndpointVO>>` | 搜索端点(keyword/method/path) |
|
||
| GET | `/apidoc/ai/project/{key}/changes` | `Result<List<ApiChangeVO>>` | API 变更(增量,since参数) |
|
||
| POST | `/apidoc/ai/query` | `Result<List<AiEndpointVO>>` | AI 自然语言查询 |
|
||
|
||
**AI 接口返回示例（`GET /apidoc/ai/endpoint/{id}`）**：
|
||
|
||
```json
|
||
{
|
||
"error": 0,
|
||
"code": null,
|
||
"message": "操作成功",
|
||
"data": {
|
||
"id": 1001,
|
||
"method": "POST",
|
||
"path": "/v1/user/users",
|
||
"summary": "创建用户",
|
||
"description": "管理员创建新用户，需要管理员权限",
|
||
"deprecated": false,
|
||
"tags": ["用户管理"],
|
||
"auth": "需要 Bearer Token，角色：ADMIN",
|
||
"requestParams": [],
|
||
"pathParams": [],
|
||
"requestHeaders": [
|
||
{ "name": "Authorization", "required": true, "description": "Bearer Token" },
|
||
{ "name": "Content-Type", "required": true, "value": "application/json" }
|
||
],
|
||
"requestBody": {
|
||
"type": "object",
|
||
"required": ["username", "password", "phone"],
|
||
"properties": {
|
||
"username": { "type": "string", "description": "用户名，4-20位字母数字", "example": "zhangsan" },
|
||
"password": { "type": "string", "description": "密码，8-32位", "example": "Pass@123" },
|
||
"phone": { "type": "string", "description": "手机号", "example": "13800138000" },
|
||
"email": { "type": "string", "description": "邮箱(可选)", "example": "zhangsan@example.com" }
|
||
}
|
||
},
|
||
"response200": {
|
||
"type": "object",
|
||
"properties": {
|
||
"error": { "type": "integer", "description": "0=成功", "example": 0 },
|
||
"code": { "type": "string", "example": "SUCCESS" },
|
||
"message": { "type": "string", "example": "操作成功" },
|
||
"data": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": { "type": "integer", "description": "用户ID", "example": 1001 },
|
||
"username": { "type": "string", "example": "zhangsan" },
|
||
"created_at": { "type": "string", "format": "date-time" }
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responseError": {
|
||
"400": { "error": 400, "code": "PARAM_INVALID", "message": "参数校验失败" },
|
||
"401": { "error": 401, "code": "UNAUTHORIZED", "message": "未登录" },
|
||
"403": { "error": 403, "code": "FORBIDDEN", "message": "无权限" }
|
||
},
|
||
"extra": {
|
||
"customTitle": "创建新用户",
|
||
"customDesc": "管理员通过此接口创建新用户，创建后用户处于启用状态",
|
||
"useCases": "后台管理 > 用户管理 > 新增用户",
|
||
"notes": "用户名唯一，不可重复。密码需满足复杂度要求。",
|
||
"requestExample": { "username": "zhangsan", "password": "Pass@123", "phone": "13800138000" },
|
||
"responseExample": { "error": 0, "code": null, "message": "操作成功", "data": { "id": 1001, "username": "zhangsan" } },
|
||
"testCases": [
|
||
{
|
||
"name": "正常创建",
|
||
"params": { "username": "testuser01", "password": "Pass@123", "phone": "13900139001" },
|
||
"expected": { "error": 0 }
|
||
},
|
||
{
|
||
"name": "用户名重复",
|
||
"params": { "username": "admin", "password": "Pass@123", "phone": "13900139002" },
|
||
"expected": { "error": 400, "code": "USER_EXISTS" }
|
||
}
|
||
]
|
||
},
|
||
"service": { "name": "rui-service-user", "project": "rui-framework" },
|
||
"updatedAt": "2026-06-08T10:00:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.5 同步引擎设计
|
||
|
||
```
|
||
自动同步流程：
|
||
1. rui-apidoc-task 中的定时任务(可配置周期) 或 手动触发
|
||
2. 遍历 apidoc_service 中 sync_mode=0 且 sync_status!=1 的服务
|
||
3. HTTP 请求 {service_url}/v3/api-docs 获取 OpenAPI JSON
|
||
4. 使用 JsonUtil 解析 JSON，提取所有 Path + Operation
|
||
5. 计算每个 Operation 的 content_hash，与 apidoc_endpoint 现有数据对比
|
||
6. 新增/更新/标记废弃 端点，记录变更
|
||
7. 更新 sync_status=2, last_sync_at, openapi_json
|
||
|
||
手动导入流程：
|
||
1. 管理员在管理后台粘贴 OpenAPI JSON 或上传文件
|
||
2. 同上解析入库逻辑，sync_mode=1
|
||
```
|
||
|
||
### 3.6 启动类
|
||
|
||
```java
|
||
package com.rui.apidoc.api;
|
||
|
||
import com.rui.common.security.annotation.EnableResourceServer;
|
||
import org.springframework.boot.SpringApplication;
|
||
import org.springframework.boot.autoconfigure.SpringBootApplication;
|
||
|
||
@SpringBootApplication
|
||
@EnableResourceServer
|
||
public class ApidocApplication {
|
||
public static void main(String[] args) {
|
||
SpringApplication.run(ApidocApplication.class, args);
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.7 Nacos 白名单配置
|
||
|
||
```yaml
|
||
security:
|
||
oauth2:
|
||
ignore-urls:
|
||
- /apidoc/portal/**
|
||
- /apidoc/ai/**
|
||
```
|
||
|
||
> `/apidoc/portal/**` 和 `/apidoc/ai/**` 免认证公开访问。
|
||
> `/apidoc/admin/**` 需管理员权限。
|
||
## 四、前端设计 — api-portal
|
||
|
||
### 4.1 技术栈
|
||
|
||
| 项目 | 选型 | 说明 |
|
||
|------|------|------|
|
||
| 框架 | Vue 3 + TypeScript | 组合式 API (setup)，和 admin-ui 一致 |
|
||
| 构建 | Vite 6 | 和 admin-ui 一致 |
|
||
| 样式 | UnoCSS | 原子化 CSS，和 admin-ui 一致 |
|
||
| 路由 | Vue Router 4 | 侧边栏联动 |
|
||
| HTTP | Axios | 统一封装 request，复用 admin-ui 模式 |
|
||
| 代码高亮 | Shiki | 和 VitePress 同款高亮引擎 |
|
||
| Markdown 渲染 | markdown-it + 自定义插件 | 自定义内容页 |
|
||
| 图标 | @iconify-json/carbon | 专业文档风格 |
|
||
|
||
> api-portal 是独立项目（不依赖 Element Plus），UI 全部基于 UnoCSS 原子化样式构建。
|
||
|
||
### 4.2 页面结构
|
||
|
||
#### 三栏布局（接口文档页）
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ 🏠 Rui API Portal 🔍 搜索接口... 🌙 主题 🌐 中文 │
|
||
├────────────┬──────────────────────────────────┬─────────────────┤
|
||
│ │ │ │
|
||
│ 📖 快速开始 │ POST /v1/user/users │ 请求示例 │
|
||
│ │ ━━━━━━━━━━━━━━━━━━━━ │ │
|
||
│ ▸ 用户管理 │ 创建新用户 │ curl -X POST \ │
|
||
│ 登录 │ │ /v1/user/users \│
|
||
│ 注册 │ 管理员通过此接口创建新用户，创建 │ -H 'Auth...' \ │
|
||
│ 用户列表 │ 后用户处于启用状态。 │ -d '{...}' │
|
||
│ 用户详情 │ │ │
|
||
│ 创建用户 │ ⚡ 需要管理员权限 │─────────────────│
|
||
│ 更新用户 │ 🔒 Bearer Token │ 响应示例 │
|
||
│ ▸ 订单管理 │ │ │
|
||
│ 创建订单 │ 请求参数 │ 200 OK │
|
||
│ 查询订单 │ ┌──────┬──────┬────┬────┐ │ { │
|
||
│ 取消订单 │ │ 参数 │ 类型 │必填│说明 │ │ "error":0, │
|
||
│ ▸ 支付 │ ├──────┼──────┼────┼────┤ │ "data":{...}│
|
||
│ 发起支付 │ │username│string│ ✓ │用户名│ │ } │
|
||
│ 支付回调 │ │password│string│ ✓ │密码 │ │ │
|
||
│ 退款 │ └──────┴──────┴────┴────┘ │─────────────────│
|
||
│ │ │ 测试用例 │
|
||
│ │ 响应参数 │ ✅ 正常创建 │
|
||
│ │ ┌──────┬──────┬────┐ │ ❌ 用户名重复 │
|
||
│ │ │ 字段 │ 类型 │说明 │ │ │
|
||
│ │ ├──────┼──────┼────┤ │ │
|
||
│ │ │ id │ long │用户ID│ │ │
|
||
│ │ └──────┴──────┴────┘ │ │
|
||
│ │ │ │
|
||
└────────────┴──────────────────────────────────┴─────────────────┘
|
||
```
|
||
|
||
#### 项目首页
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ 🏠 Rui API Portal 🔍 搜索接口... 🌙 主题 🌐 中文 │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ 睿核科技 API 文档中心 │
|
||
│ 探索、测试、集成我们的 API 服务 │
|
||
│ │
|
||
│ ┌──────────────────────────────────┐ │
|
||
│ │ 🔍 搜索所有 API 接口... │ │
|
||
│ └──────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||
│ │ 📦 rui-frame │ │ 📦 rui-cashier│ │ 📦 rui-payment│ │
|
||
│ │ work │ │ │ │ │ │
|
||
│ │ 基础平台框架 │ │ 收银系统 │ │ 支付系统 │ │
|
||
│ │ 128 接口 │ │ 56 接口 │ │ 32 接口 │ │
|
||
│ │ 5 模块 │ │ 3 模块 │ │ 2 模块 │ │
|
||
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 4.3 路由设计
|
||
|
||
```
|
||
/ → 项目首页（项目卡片列表）
|
||
/:projectKey → 项目页（菜单 + 欢迎页）
|
||
/:projectKey/menu/:menuId → 菜单页（自定义内容 / 接口组）
|
||
/:projectKey/endpoint/:id → 单个接口详情页
|
||
/search?keyword=&projectId= → 搜索结果页
|
||
```
|
||
|
||
### 4.4 核心功能
|
||
|
||
| 功能 | 说明 |
|
||
|------|------|
|
||
| 多级菜单导航 | 3 级可折叠侧边栏，图标 + 名称 |
|
||
| 接口文档渲染 | 方法/路径/参数/响应/示例，结构化表格展示 |
|
||
| 代码高亮 | 请求示例(curl/JS/Java)、响应示例 JSON |
|
||
| Markdown 自定义页 | 菜单项关联自定义 Markdown 内容（快速开始、认证说明等） |
|
||
| 全文搜索 | 搜索接口名、路径、描述、参数名 |
|
||
| 深色模式 | 主题切换 |
|
||
| 响应式 | 移动端适配（侧边栏折叠） |
|
||
| "试一试" | 简易 API 测试面板（填参数发请求） |
|
||
|
||
### 4.5 项目结构
|
||
|
||
> 遵循 admin-ui 的目录约定：service 层使用 BaseService 模式，composables 存放组合式函数，views 存放页面。
|
||
|
||
```
|
||
api-portal/
|
||
├── package.json
|
||
├── vite.config.ts
|
||
├── uno.config.ts
|
||
├── tsconfig.json
|
||
├── index.html
|
||
├── public/
|
||
│ └── favicon.svg
|
||
├── src/
|
||
│ ├── main.ts
|
||
│ ├── App.vue
|
||
│ ├── service/ # API 请求封装（和 admin-ui 一致）
|
||
│ │ ├── BaseService.ts # 通用 CRUD 基类（复用 admin-ui 模式）
|
||
│ │ ├── portalService.ts # 文档门户接口
|
||
│ │ └── types.ts # TypeScript 类型定义
|
||
│ ├── composables/ # 组合式函数
|
||
│ │ ├── useTheme.ts # 主题切换
|
||
│ │ ├── useMenu.ts # 菜单状态
|
||
│ │ └── useSearch.ts # 搜索
|
||
│ ├── components/
|
||
│ │ ├── layout/
|
||
│ │ │ ├── AppHeader.vue # 顶部导航
|
||
│ │ │ ├── AppSidebar.vue # 侧边栏
|
||
│ │ │ ├── AppFooter.vue # 底部
|
||
│ │ │ └── ThreeColumn.vue # 三栏布局容器
|
||
│ │ ├── endpoint/
|
||
│ │ │ ├── EndpointHeader.vue # 方法 + 路径 + 标签
|
||
│ │ │ ├── ParamsTable.vue # 参数表格
|
||
│ │ │ ├── ResponseSchema.vue # 响应结构
|
||
│ │ │ ├── CodeBlock.vue # 代码块(Shiki 高亮)
|
||
│ │ │ └── TryIt.vue # "试一试"面板
|
||
│ │ ├── markdown/
|
||
│ │ │ └── MarkdownRenderer.vue # Markdown 渲染
|
||
│ │ └── search/
|
||
│ │ └── SearchDialog.vue # 搜索弹窗
|
||
│ ├── views/ # 页面（和 admin-ui 命名一致）
|
||
│ │ ├── HomePage.vue # 首页
|
||
│ │ ├── ProjectPage.vue # 项目页
|
||
│ │ ├── MenuPage.vue # 菜单内容页
|
||
│ │ ├── EndpointPage.vue # 接口详情页
|
||
│ │ └── SearchPage.vue # 搜索结果页
|
||
│ ├── router/
|
||
│ │ └── index.ts
|
||
│ ├── stores/ # Pinia 状态管理
|
||
│ │ └── project.ts # 项目状态
|
||
│ ├── styles/
|
||
│ │ ├── variables.css # CSS 变量(主题色)
|
||
│ │ └── prose.css # 文档内容样式
|
||
│ └── utils/
|
||
│ ├── request.ts # Axios 封装（复用 admin-ui 模式，baseURL 指向 apidoc 服务）
|
||
│ └── format.ts # 格式化工具
|
||
└── env.d.ts
|
||
```
|
||
|
||
### 4.6 request.ts 设计
|
||
|
||
> 复用 admin-ui 的 request 封装模式，但 api-portal 是公开文档站，不需要 Token/租户拦截。
|
||
|
||
```typescript
|
||
// src/utils/request.ts
|
||
import axios from 'axios'
|
||
|
||
const request = axios.create({
|
||
baseURL: '/api', // 通过网关转发到 rui-apidoc
|
||
timeout: 10000,
|
||
})
|
||
|
||
// 响应拦截 — 复用 Result<T> 的 error 判断逻辑
|
||
request.interceptors.response.use(
|
||
(response) => {
|
||
const { data } = response
|
||
if (data.error !== 0) {
|
||
console.error(data.message || '请求失败')
|
||
return Promise.reject(data)
|
||
}
|
||
return data
|
||
},
|
||
(error) => {
|
||
console.error('网络错误', error.message)
|
||
return Promise.reject(error)
|
||
},
|
||
)
|
||
|
||
export { request }
|
||
```
|
||
|
||
### 4.7 service 层设计
|
||
|
||
> 遵循 admin-ui 的 BaseService 模式，但 api-portal 以只读查询为主。
|
||
|
||
```typescript
|
||
// src/service/portalService.ts
|
||
import { request } from '@/utils/request'
|
||
|
||
/** 获取公开项目列表 */
|
||
export function getProjectList() {
|
||
return request({ url: '/apidoc/portal/project/list', method: 'get' })
|
||
}
|
||
|
||
/** 获取项目详情 */
|
||
export function getProject(key: string) {
|
||
return request({ url: `/apidoc/portal/project/${key}`, method: 'get' })
|
||
}
|
||
|
||
/** 获取项目菜单树 */
|
||
export function getMenuTree(key: string) {
|
||
return request({ url: `/apidoc/portal/project/${key}/menu`, method: 'get' })
|
||
}
|
||
|
||
/** 获取菜单详情 */
|
||
export function getMenuDetail(key: string, menuId: string) {
|
||
return request({ url: `/apidoc/portal/project/${key}/menu/${menuId}`, method: 'get' })
|
||
}
|
||
|
||
/** 获取端点详情 */
|
||
export function getEndpoint(id: string) {
|
||
return request({ url: `/apidoc/portal/endpoint/${id}`, method: 'get' })
|
||
}
|
||
|
||
/** 搜索 */
|
||
export function searchEndpoints(keyword: string, projectId?: string) {
|
||
return request({ url: '/apidoc/portal/search', method: 'get', params: { keyword, projectId } })
|
||
}
|
||
```
|
||
## 五、部署架构
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────┐
|
||
│ Nginx / Gateway │
|
||
│ ├─ / → api-portal 静态资源 │
|
||
│ ├─ /admin → admin-ui 静态资源 │
|
||
│ └─ /api/apidoc/* → rui-service-apidoc │
|
||
└──────────────────────────────────────────────────┘
|
||
|
||
api-portal 构建产物部署为静态资源，通过 Nginx 或 CDN 分发。
|
||
rui-service-apidoc 注册到 Nacos，通过 Gateway 路由。
|
||
```
|
||
|
||
---
|
||
|
||
## 六、开发优先级
|
||
|
||
### Phase 1：MVP（最小可用）
|
||
|
||
1. 后端：项目/菜单/端点 CRUD + OpenAPI JSON 手动导入
|
||
2. 前端：三栏布局 + 菜单导航 + 接口文档渲染
|
||
|
||
### Phase 2：增强
|
||
|
||
3. 后端：自动同步引擎（定时拉取 /v3/api-docs）
|
||
4. 后端：文档补全管理
|
||
5. 前端：搜索 + 深色模式
|
||
|
||
### Phase 3：AI + 高级功能
|
||
|
||
6. 后端：AI 专用结构化接口
|
||
7. 后端：API 变更检测 + 版本管理
|
||
8. 前端："试一试" API 测试面板
|
||
|
||
---
|
||
|
||
## 七、参考风格
|
||
|
||
| 参考站点 | 地址 | 借鉴点 |
|
||
|---------|------|--------|
|
||
| VitePress | https://vitepress.dev | 整体风格、三栏布局、深色模式 |
|
||
| Nuxt UI Pro | https://ui.nuxt.com/pro | 文档模板、导航设计 |
|
||
| Stripe API | https://stripe.com/docs/api | 代码示例、交互体验 |
|
||
| Scalar | https://scalar.com | 现代 API 文档 UI |
|
||
|
||
---
|
||
|
||
> 本文档仅涵盖设计，不涉及具体实现代码。实施前需团队审核确认。
|