@smart-portal/smart-api v1.0.8

Smart API 工具

Smart API 是一个基于 MCP (Model Context Protocol) 的智能 API 文档解析和查询工具服务。该服务能够加载 OpenAPI 3.0 规范的 YAML/JSON 文件，解析其中的 API 端点信息，并提供一系列工具函数，帮助前端工程师在前后端接口联调过程中快速获取 API 信息。

主要功能

1. 加载并解析 OpenAPI 3.0 规范文件
2. 列出所有可用的 API 端点
3. 获取特定 API 端点的详细信息
4. 生成 API 请求响应模板

新增功能

流式解析大型API文档

为了提高处理大型 API 文档的能力，Smart API 现在支持流式解析功能：

• 流式读取与解析：使用 Node.js 的文件流接口处理大型 YAML/JSON 文件，减少内存占用
• 配置化阈值：可以配置触发流式处理的文件大小阈值，默认为 5MB
• 分块处理：将大型文档分成多个小块进行处理，有效降低内存峰值

选择性加载部分API内容

为了优化内存使用和提高处理速度，Smart API 支持选择性加载 API 文档：

• 路径前缀过滤：只加载指定路径前缀的 API 端点，如 /api/v1/users
• 标签过滤：只加载包含特定标签的 API 端点，如 users, products
• 操作 ID 过滤：只加载特定操作 ID 的 API 端点，如 getUserById, createUser

内存优化策略

Smart API 采用了多种内存优化策略：

• LRU 缓存策略：使用最近最少使用（LRU）策略管理引用缓存
• 批量处理：分批处理 API 路径，避免一次性加载过多内容导致内存占用过高
• 垃圾回收提示：在适当时机提示垃圾回收器回收不再需要的对象

使用方法

基本用法

import { createApiService, createApiStore, Logger } from "./smart-api";

const logger = new Logger();
const apiStore = createApiStore(logger);
const apiService = createApiService(apiStore, logger);

// 加载 API 规范
await apiService.loadApiSpec("/path/to/openapi.yaml", "yaml");

// 列出所有 API 端点
const endpoints = apiService.getApiEndpointList();

// 获取特定 API 端点详情
const endpoint = apiService.describeApiEndpoint("getUserById");

// 生成 API 请求模板
const template = apiService.generateTemplateAndCallApi("getUserById");

使用流式解析和选择性加载

import { createApiService, createApiStore, Logger } from "./smart-api";

const logger = new Logger();
const apiStore = createApiStore(logger, {
  memoryOptimization: {
    enableGCHints: true,
    refCacheSize: 2000,
  },
});

// 使用流式解析和选择性加载配置创建服务
const apiService = createApiService(apiStore, logger, {
  streamOptions: {
    useStreaming: true,
    streamingThreshold: 1024 * 1024 * 2, // 2MB 文件大小触发流式解析
  },
  selectiveLoadOptions: {
    enabled: true,
    pathPrefixes: ["/api/v1/users"],
    tags: ["users", "admin"],
  },
});

// 加载 API 规范
await apiService.loadApiSpec("/path/to/large-openapi.yaml", "yaml");

注意事项

• 流式解析功能需要 Node.js 10.0 或更高版本
• 选择性加载可能会忽略一些 API 端点，请确保指定了正确的过滤条件
• 内存优化策略可能会影响性能，根据实际需求进行配置

配置选项

ApiStore 配置选项

interface ApiStoreConfig {
  cacheEnabled?: boolean;
  memoryOptimization?: {
    enableGCHints?: boolean;
    lazyRefResolution?: boolean;
    refCacheSize?: number;
  };
}

ApiService 配置选项

interface ApiServiceConfig {
  templateOptions?: {
    includeExamples?: boolean;
    includeAssertions?: boolean;
  };
  streamOptions?: {
    chunkSize?: number;
    useStreaming?: boolean;
    streamingThreshold?: number;
  };
  selectiveLoadOptions?: {
    enabled?: boolean;
    pathPrefixes?: string[];
    tags?: string[];
    operationIds?: string[];
  };
}

贡献

欢迎提交 issue 和 pull request 来帮助改进 Smart API 工具。