Mcp-Swagger-Server

# MCP Swagger UI 架构设计文档 ## 整体架构图 ``` ┌─────────────────────────────────────────────────────────────┐ │ 用户界面层 (UI Layer) │ ├─────────────────────────────────────────────────────────────┤ │ Home.vue │ │ ┌─────────────────┬─────────────────┬─────────────────┐ │ │ │ 输入区域 │ 预览区域 │ 配置区域 │ │ │ │ ─────────────── │ ─────────────── │ ─────────────── │ │ │ │ • URL 输入 │ • API 信息 │ • HTTP 方法 │ │ │ │ • 文件上传 │ • 端点列表 │ • 标签过滤 │ │ │ │ • 文本粘贴 │ • 状态显示 │ • 高级选项 │ │ │ └─────────────────┴─────────────────┴─────────────────┘ │ │ 结果区域 │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ • MCP 配置预览 • 下载功能 • 复制功能 • 启动命令 │ │ │ └─────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ↕ (Vue Router) ┌─────────────────────────────────────────────────────────────┐ │ 状态管理层 (State Layer) │ ├─────────────────────────────────────────────────────────────┤ │ Pinia Store │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ AppStore (stores/app.ts) │ │ │ │ ├─ State: │ │ │ │ │ • inputSource: InputSource │ │ │ │ │ • config: ConvertConfig │ │ │ │ │ • apiInfo: OpenApiInfo │ │ │ │ │ • endpoints: ApiEndpoint[] │ │ │ │ │ • convertResult: ConvertResult │ │ │ │ │ • loading: boolean │ │ │ │ │ • error: string │ │ │ │ ├─ Getters: │ │ │ │ │ • isValidInput │ │ │ │ │ • availableTags │ │ │ │ │ • filteredEndpoints │ │ │ │ ├─ Actions: │ │ │ │ │ • setInputSource() │ │ │ │ │ • validateInput() │ │ │ │ │ • previewApi() │ │ │ │ │ • convertToMcp() │ │ │ │ └─ Mutations: (通过 Actions 自动处理) │ │ │ └─────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ↕ (Axios HTTP) ┌─────────────────────────────────────────────────────────────┐ │ 服务层 (Service Layer) │ ├─────────────────────────────────────────────────────────────┤ │ API Service │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ utils/api.ts │ │ │ │ ├─ validateApi(source): 验证 OpenAPI 规范 │ │ │ │ ├─ previewApi(source): 预览 API 信息 │ │ │ │ ├─ convertApi(params): 转换为 MCP 格式 │ │ │ │ ├─ downloadFile(): 文件下载工具 │ │ │ │ └─ copyToClipboard(): 剪贴板操作 │ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ utils/demo-data.ts (演示模式数据) │ │ │ │ ├─ demoApiInfo: 演示 API 信息 │ │ │ │ ├─ demoEndpoints: 演示端点数据 │ │ │ │ └─ demoConvertResult: 演示转换结果 │ │ │ └─────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ↕ (HTTP/WebSocket) ┌─────────────────────────────────────────────────────────────┐ │ 后端服务 (Backend) │ ├─────────────────────────────────────────────────────────────┤ │ MCP Swagger Server │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ HTTP API 端点: │ │ │ │ ├─ POST /api/validate - 验证 OpenAPI 规范 │ │ │ │ ├─ POST /api/preview - 预览 API 信息 │ │ │ │ └─ POST /api/convert - 转换为 MCP 格式 │ │ │ └─────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` ## 数据流图 ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ 用户输入 │ │ 状态管理 │ │ API 调用 │ │ │ │ │ │ │ │ • URL 地址 │───▶│ setInputSource │───▶│ validateApi │ │ • 上传文件 │ │ │ │ │ │ • 粘贴文本 │ │ ┌─────────────┐ │ │ ┌─────────────┐ │ │ │ │ │ inputSource │ │ │ │ 验证结果 │ │ └─────────────────┘ │ │ config │ │ │ └─────────────┘ │ │ │ loading │ │ │ │ ┌─────────────────┐ │ │ error │ │ │ previewApi │ │ 配置选项 │───▶│ └─────────────┘ │───▶│ │ │ │ │ │ │ ┌─────────────┐ │ │ • HTTP 方法 │ │ setConfig │ │ │ API 信息 │ │ │ • 标签过滤 │ │ │ │ │ 端点列表 │ │ │ • 高级选项 │ │ ┌─────────────┐ │ │ └─────────────┘ │ │ │ │ │ apiInfo │ │ │ │ └─────────────────┘ │ │ endpoints │ │◀───│ convertApi │ │ └─────────────┘ │ │ │ ┌─────────────────┐ │ │ │ ┌─────────────┐ │ │ 用户操作 │ │ convertToMcp │ │ │ MCP 配置 │ │ │ │───▶│ │ │ │ 工具列表 │ │ │ • 转换按钮 │ │ ┌─────────────┐ │ │ │ 元数据 │ │ │ • 验证按钮 │ │ │convertResult│ │◀───│ └─────────────┘ │ │ • 下载按钮 │ │ └─────────────┘ │ │ │ │ │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ ▼ ┌─────────────────┐ │ 用户界面 │ │ │ │ • 进度指示器 │ │ • 预览面板 │ │ • 结果展示 │ │ • 错误提示 │ │ │ └─────────────────┘ ``` ## 组件关系图 ``` App.vue ├─ router-view └─ Home.vue (主页面) ├─ 输入部分 (内联组件) │ ├─ URL 输入标签页 │ ├─ 文件上传标签页 │ └─ 文本输入标签页 │ ├─ 预览部分 (内联组件) │ ├─ API 基本信息卡片 │ ├─ 端点列表网格 │ └─ 状态徽章 │ ├─ 配置部分 (内联组件) │ ├─ HTTP 方法过滤 │ ├─ 标签过滤 │ ├─ 高级选项 │ └─ 传输协议选择 │ └─ 结果部分 (内联组件) ├─ MCP 配置预览 ├─ 下载按钮 ├─ 复制按钮 └─ 启动命令 ``` ## 状态管理流程 ``` ┌─────────────────┐ Action ┌─────────────────┐ │ Vue 组件 │─────────────▶│ Pinia Store │ │ │ │ │ │ • 用户交互 │ │ • 状态更新 │ │ • 事件触发 │ │ • 副作用处理 │ │ • 生命周期 │ │ • API 调用 │ │ │ │ │ └─────────────────┘ └─────────────────┘ ▲ │ │ │ State Change │ ▼ ┌─────────────────┐ Reactive ┌─────────────────┐ │ Vue 响应式 │◀─────────────│ Store State │ │ │ │ │ │ • 重新渲染 │ │ • inputSource │ │ • 计算属性 │ │ • config │ │ • 监听器 │ │ • apiInfo │ │ │ │ • endpoints │ └─────────────────┘ │ • convertResult │ │ • loading │ │ • error │ └─────────────────┘ ``` ## API 调用流程 ``` ┌─────────────────┐ │ 用户触发操作 │ │ (点击转换按钮) │ └─────────┬───────┘ │ ▼ ┌─────────────────┐ │ Home.vue │ │ handleConvert() │ └─────────┬───────┘ │ ▼ ┌─────────────────┐ │ AppStore │ │ setInputSource()│ │ previewApi() │ │ convertToMcp() │ └─────────┬───────┘ │ ▼ ┌─────────────────┐ HTTP ┌─────────────────┐ │ API Service │───────────▶│ Backend API │ │ utils/api.ts │ │ │ │ │◀───────────│ • /api/preview │ │ • 请求封装 │ Response │ • /api/convert │ │ • 错误处理 │ │ • /api/validate │ │ • 响应解析 │ │ │ └─────────┬───────┘ └─────────────────┘ │ ▼ ┌─────────────────┐ │ Store 状态更新 │ │ • loading: true │ │ • apiInfo: data │ │ • convertResult │ │ • error: null │ └─────────┬───────┘ │ ▼ ┌─────────────────┐ │ UI 自动更新 │ │ • 显示进度 │ │ • 展示结果 │ │ • 处理错误 │ └─────────────────┘ ``` ## 类型系统架构 ``` types/index.ts ├─ InputSource - 输入源类型 │ ├─ type: 'url' | 'file' | 'text' │ ├─ content: string │ └─ auth?: AuthConfig │ ├─ ConvertConfig - 转换配置 │ ├─ filters: FilterConfig │ ├─ transport: TransportType │ └─ optimization: OptimizationConfig │ ├─ OpenApiInfo - API 基本信息 │ ├─ title: string │ ├─ version: string │ ├─ description?: string │ └─ serverUrl?: string │ ├─ ApiEndpoint - API 端点 │ ├─ method: string │ ├─ path: string │ ├─ summary?: string │ ├─ tags?: string[] │ └─ deprecated?: boolean │ ├─ ConvertResult - 转换结果 │ ├─ mcpConfig: McpConfig │ ├─ metadata: ResultMetadata │ └─ processingTime: number │ └─ AppState - 应用状态 ├─ inputSource: InputSource ├─ config: ConvertConfig ├─ apiInfo: OpenApiInfo | null ├─ endpoints: ApiEndpoint[] ├─ convertResult: ConvertResult | null ├─ loading: boolean └─ error: string | null ``` ## 构建和部署架构 ``` 开发环境 (Development) ├─ Vite Dev Server (Port 3000) │ ├─ HMR (热模块替换) │ ├─ TypeScript 编译 │ ├─ Vue SFC 处理 │ └─ API 代理 (/api → localhost:3322) │ ├─ 自动导入 │ ├─ Vue APIs (ref, reactive, computed...) │ ├─ Router APIs (useRouter, useRoute...) │ ├─ Pinia APIs (defineStore, storeToRefs...) │ └─ Element Plus 组件 │ └─ 开发工具 ├─ Vue DevTools ├─ TypeScript 类型检查 ├─ ESLint 代码检查 └─ Prettier 代码格式化 生产环境 (Production) ├─ 构建输出 (dist/) │ ├─ HTML 模板 │ ├─ JavaScript 包 │ │ ├─ 主应用包 │ │ ├─ Element Plus 包 │ │ └─ Monaco Editor 包 │ ├─ CSS 样式 │ └─ 静态资源 │ ├─ 优化策略 │ ├─ 代码分割 (Code Splitting) │ ├─ Tree Shaking │ ├─ 资源压缩 │ └─ 缓存策略 │ └─ 部署选项 ├─ 静态文件服务器 ├─ CDN 分发 └─ Docker 容器化 ``` 这个架构设计文档提供了 MCP Swagger UI 项目的完整架构视图，包括组件关系、数据流、状态管理和构建部署等各个方面的详细说明。