# openapiui

**Repository Path**: one529/openapiui

## Basic Information

- **Project Name**: openapiui
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-07
- **Last Updated**: 2026-03-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenAPI UI

基于 React + TypeScript + Vite 的 OpenAPI 文档可视化工具，提供类似 Swagger UI 的交互式 API 文档浏览和调试功能。

## 特性

- 📚 **OpenAPI 规范支持** - 自动解析 OpenAPI 3.x 规范，生成可交互的 API 文档
- 🎨 **现代化 UI** - 使用 shadcn/ui 组件库，支持亮色/暗色主题
- 🔧 **API 调试** - 内置 API 测试工具，支持参数配置、请求头发送、响应查看
- 🧪 **测试用例管理** - 支持保存、重命名、复制、删除测试用例，用例数据自动缓存到浏览器
- 🔐 **登录认证** - 支持登录认证，自动定时校验登录状态
- ⚙️ **全局配置** - 支持配置全局请求头和 Cookie
- 📱 **响应式设计** - 适配各种屏幕尺寸
- 🚀 **快速构建** - 基于 Vite，开发体验流畅

## 技术栈

- **框架**: React 19 + TypeScript
- **构建工具**: Vite 8
- **UI 组件**: shadcn/ui + Tailwind CSS 4
- **状态管理**: Zustand
- **HTTP 客户端**: Axios
- **图标**: Lucide React

## 快速开始

### 安装依赖

```bash
pnpm install
```

### 开发环境

```bash
pnpm dev
```

### 构建生产版本

```bash
pnpm build
```

### 预览生产构建

```bash
pnpm preview
```

## 后端对接样例

如果你使用 .NET 后端，可以参考以下样例项目快速集成：

🔗 **[OpenApiUI.Net](https://gitee.com/one529/open-api-ui.-net)** - 基于 ASP.NET Core 的轻量级 API 文档 UI 组件库

该样例项目提供了：
- 完整的后端集成示例
- Swagger/Swashbuckle 配置
- 登录认证实现（JWT Token）
- 多版本 API 文档切换
- 认证接口实现（`IOpenApiUiAuthService`）

## 配置说明

项目通过 `public/config.json` 进行配置：

### 配置示例

```json
{
  "title": "API 文档",
  "docPaths": [
    "/swagger/v1/swagger.json",
    "/swagger/v2/swagger.json",
    "/swagger/v3/swagger.json"
  ],
  "headers": {
    "Content-Type": "application/json"
  },
  "cookies": {
    "sessionId": "your-session-id"
  },
  "auth": {
    "enabled": true,
    "title": "登录"
  }
}
```

### 配置项说明

| 配置项 | 类型 | 说明 |
|--------|------|------|
| `title` | string | 页面标题 |
| `docPaths` | string[] | OpenAPI 文档路径数组 |
| `headers` | object | 默认全局请求头 |
| `cookies` | object | 默认全局 Cookie |
| `auth.enabled` | boolean | 是否启用登录 |
| `auth.title` | string | 登录页面标题 |

## 环境变量

项目支持通过 `.env` 文件配置 Vite 代理：

```env
# API 代理前缀（开发环境下使用）
VITE_API_PREFIX=/api

# 代理目标地址（开发环境下使用）
VITE_PROXY_TARGET=http://localhost:5152

# OpenAPI 配置接口路径
VITE_OPENAPI_CONFIG_PATH=/openapi-ui/config

# OpenAPI 登录接口路径
VITE_OPENAPI_AUTH_PATH=/openapi-ui/auth

# OpenAPI 校验认证状态接口路径
VITE_OPENAPI_CHECK_AUTH_PATH=/openapi-ui/check-auth
```

## 项目结构

```
src/
├── components/          # 组件目录
│   ├── api/            # API 相关组件
│   │   ├── debug-view/ # API 调试视图（含测试用例保存功能）
│   │   └── doc-view/   # API 文档视图
│   ├── auth/           # 认证相关组件
│   ├── layout/         # 布局组件（Sidebar、ApiTabs 等）
│   └── ui/             # UI 组件（shadcn/ui）
├── lib/                # 工具函数
├── stores/             # 状态管理（Zustand，含用例本地存储逻辑）
├── types/              # TypeScript 类型定义
└── App.tsx             # 应用入口
```

## 测试用例管理

在 API 调试页面，可以将当前请求配置保存为测试用例，方便后续快速调用：

- **保存用例** - 将当前请求参数、请求头等保存为测试用例
- **用例管理** - 在左侧菜单栏可以查看、切换、管理所有用例
- **用例操作** - 支持重命名、复制、删除用例（点击用例右侧的菜单按钮）
- **名称唯一性** - 同一接口下的用例名称不允许重复
- **数据持久化** - 用例数据自动缓存到浏览器 localStorage，刷新页面后数据不丢失

## 全局配置

点击顶部导航栏的设置图标，可以配置全局请求头和 Cookie：

- **请求头** - 自动添加到所有 API 请求的 HTTP 头
- **Cookie** - 自动添加到所有 API 请求的 Cookie

配置会自动保存到浏览器本地存储。

## 登录认证

### 登录接口

**请求路径**: `POST /openapi-ui/auth`

**请求参数**:
```json
{
  "username": "用户名",
  "password": "密码"
}
```

**响应数据**:
```json
{
  "headers": {
    "X-Custom-Header": "value"
  },
  "cookies": {
    "sessionId": "session-value"
  }
}
```

登录成功后，返回的 headers 和 cookies 会自动合并到全局配置中。

### 校验认证状态接口

应用会每分钟自动调用一次校验接口来检查用户登录状态。

**请求路径**: `POST /openapi-ui/check-auth`

**请求参数**: 无（请求体为空）

**请求头**: 自动携带全局配置中的请求头

**响应数据**:
```json
true
```

如果校验返回 `true`，表示认证有效；否则应用会自动退出登录并跳转到登录页面。

## 许可证

MIT