swagger2api-v3 1.1.10 → 1.1.11

package/dist/types/index.d.ts

@@ -7,7 +7,7 @@
 export interface SwaggerConfig {
     /** 本地 JSON Schema 路径，用于编辑器提示 */
     $schema?: string;
-    /** Swagger JSON 文件路径或 URL */
+    /** OpenAPI 3.0 JSON/YAML 文件路径或 URL */
     input: string;
     /** 输出目录 */
     output: string;
@@ -110,6 +110,13 @@ export interface SwaggerDocument {
     components?: SwaggerComponents;
     tags?: SwaggerTag[];
 }
+/**
+ * OpenAPI 引用对象
+ */
+export interface SwaggerReference {
+    /** 引用地址 */
+    $ref: string;
+}
 /**
  * OpenAPI Server 对象
  */
@@ -163,6 +170,8 @@ export interface SwaggerPaths {
  * Swagger路径项
  */
 export interface SwaggerPathItem {
+    /** Path Item 引用 */
+    $ref?: string;
     get?: SwaggerOperation;
     post?: SwaggerOperation;
     put?: SwaggerOperation;
@@ -170,6 +179,7 @@ export interface SwaggerPathItem {
     patch?: SwaggerOperation;
     head?: SwaggerOperation;
     options?: SwaggerOperation;
+    trace?: SwaggerOperation;
     parameters?: SwaggerParameter[];
 }
 /**
@@ -192,7 +202,7 @@ export interface SwaggerRequestBody {
     /** 本地引用路径 */
     $ref?: string;
     description?: string;
-    content: {
+    content?: {
         [mediaType: string]: {
             schema?: SwaggerSchema;
             example?: any;
@@ -224,13 +234,15 @@ export interface SwaggerParameter {
  * OpenAPI 响应
  */
 export interface SwaggerResponses {
-    [statusCode: string]: SwaggerResponse;
+    [statusCode: string]: SwaggerResponse | SwaggerReference;
 }
 /**
  * OpenAPI 响应项
  */
 export interface SwaggerResponse {
-    description: string;
+    /** 本地或已打包的引用路径 */
+    $ref?: string;
+    description?: string;
     content?: {
         [mediaType: string]: {
             schema?: SwaggerSchema;
@@ -281,7 +293,7 @@ export interface SwaggerSchema {
     $ref?: string;
     example?: any;
     examples?: any[];
-    discriminator?: string;
+    discriminator?: OpenAPIDiscriminator;
     readOnly?: boolean;
     writeOnly?: boolean;
     xml?: SwaggerXml;
@@ -293,6 +305,15 @@ export interface SwaggerSchema {
     /** OpenAPI 扩展字段：枚举名称 */
     'x-enumNames'?: string[];
 }
+/**
+ * OpenAPI discriminator 对象
+ */
+export interface OpenAPIDiscriminator {
+    /** 用作类型判别的属性名 */
+    propertyName: string;
+    /** 判别值到 Schema 引用的映射 */
+    mapping?: Record<string, string>;
+}
 /**
  * Swagger项目
  */
@@ -312,7 +333,7 @@ export interface SwaggerComponents {
         [name: string]: SwaggerSchema;
     };
     responses?: {
-        [name: string]: SwaggerResponse;
+        [name: string]: SwaggerResponse | SwaggerReference;
     };
     parameters?: {
         [name: string]: SwaggerParameter;

package/dist/utils/comment.d.ts

@@ -13,7 +13,10 @@ export interface ApiCommentOperation {
 /**
  * 注释生成需要的参数信息
  */
-export type ApiCommentParameter = Pick<ParameterInfo, 'in' | 'description'>;
+export type ApiCommentParameter = Pick<ParameterInfo, 'in' | 'description'> & {
+    /** 生成后的函数参数名 */
+    name?: string;
+};
 /**
  * 生成接口注释
  * @param operation 接口操作信息

package/dist/utils/comment.js

@@ -23,8 +23,12 @@ function generateApiComment(operation, parameters) {
         const hasData = bodyParams.length > 0;
         if (hasParams || hasData) {
             comments.push(' *');
-            if (hasParams) {
-                const paramDescriptions = [...pathParams, ...queryParams]
+            pathParams.forEach((param, index) => {
+                const name = param.name || `pathParam${index + 1}`;
+                comments.push(` * @param ${name} ${param.description || '路径参数'}`);
+            });
+            if (queryParams.length > 0) {
+                const paramDescriptions = queryParams
                     .map((param) => param.description || '')
                     .filter((description) => description)
                     .join(', ');

package/dist/utils/file.d.ts

@@ -10,9 +10,16 @@ export declare function ensureDirectoryExists(dirPath: string): void;
  */
 export declare function removeDirectory(dirPath: string): void;
 /**
- * 读取Swagger文档
- * @param input 文件路径或URL
- * @returns Swagger文档对象
+ * 判断目标路径是否严格位于父路径内部
+ * @param parentPath 父路径
+ * @param targetPath 目标路径
+ * @returns 目标路径是否位于父路径内部
+ */
+export declare function isPathInside(parentPath: string, targetPath: string): boolean;
+/**
+ * 读取并打包 OpenAPI 3.0 文档
+ * @param input 文件路径或 URL
+ * @returns OpenAPI 文档对象
  */
 export declare function loadSwaggerDocument(input: string): Promise<SwaggerDocument>;
 /**

package/dist/utils/file.js

@@ -32,17 +32,15 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ensureDirectoryExists = ensureDirectoryExists;
 exports.removeDirectory = removeDirectory;
+exports.isPathInside = isPathInside;
 exports.loadSwaggerDocument = loadSwaggerDocument;
 exports.writeFile = writeFile;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
-const axios_1 = __importDefault(require("axios"));
+const OpenAPIParser = require("@apidevtools/swagger-parser");
 const logger_1 = require("./logger");
 /**
  * 确保目录存在，如果不存在则创建
@@ -63,28 +61,59 @@ function removeDirectory(dirPath) {
     }
 }
 /**
- * 读取Swagger文档
- * @param input 文件路径或URL
- * @returns Swagger文档对象
+ * 判断目标路径是否严格位于父路径内部
+ * @param parentPath 父路径
+ * @param targetPath 目标路径
+ * @returns 目标路径是否位于父路径内部
+ */
+function isPathInside(parentPath, targetPath) {
+    const relativePath = path.relative(path.resolve(parentPath), path.resolve(targetPath));
+    return (relativePath !== '' &&
+        relativePath !== '..' &&
+        !relativePath.startsWith(`..${path.sep}`) &&
+        !path.isAbsolute(relativePath));
+}
+/**
+ * 读取并打包 OpenAPI 3.0 文档
+ * @param input 文件路径或 URL
+ * @returns OpenAPI 文档对象
  */
 async function loadSwaggerDocument(input) {
     try {
-        if (input.startsWith('http://') || input.startsWith('https://')) {
-            const { data } = await axios_1.default.get(input);
-            logger_1.logger.debug(`从 URL 加载: ${input}`);
-            if (data.components?.schemas) {
-                logger_1.logger.debugKV('schemas 数量', Object.keys(data.components.schemas).length);
-            }
-            else {
-                logger_1.logger.debug('加载的数据中未发现 schemas');
+        const isRemoteInput = /^https?:\/\//i.test(input);
+        const resolveOptions = isRemoteInput
+            ? {
+                file: false,
+                http: {
+                    timeout: 15000,
+                    safeUrlResolver: false
+                }
             }
-            return data;
+            : {
+                http: {
+                    timeout: 15000,
+                    safeUrlResolver: false
+                }
+            };
+        const data = (await OpenAPIParser.bundle(input, {
+            resolve: resolveOptions
+        }));
+        if (isRemoteInput) {
+            logger_1.logger.debug(`从 URL 加载: ${input}`);
+        }
+        else {
+            logger_1.logger.debug(`从文件加载: ${path.resolve(input)}`);
+        }
+        if (data.components?.schemas) {
+            logger_1.logger.debugKV('schemas 数量', Object.keys(data.components.schemas).length);
+        }
+        else {
+            logger_1.logger.debug('加载的数据中未发现 schemas');
         }
-        const content = fs.readFileSync(input, 'utf-8');
-        return JSON.parse(content);
+        return data;
     }
     catch (error) {
-        throw new Error(`Failed to load Swagger document from ${input}: ${error}`);
+        throw new Error(`Failed to load OpenAPI document from ${input}: ${error}`);
     }
 }
 /**

package/dist/utils/naming.js

@@ -118,7 +118,8 @@ function sanitizeFilename(filename) {
  */
 function sanitizeTypeName(name) {
     if (!name)
-        return name;
+        return 'AnonymousType';
     const replaced = name.replace(/[^a-zA-Z0-9_]/g, '_');
-    return toPascalCase(replaced);
+    const typeName = toPascalCase(replaced) || 'AnonymousType';
+    return /^\d/.test(typeName) ? `_${typeName}` : typeName;
 }

package/dist/utils/schema.d.ts

@@ -0,0 +1,79 @@
+import { SwaggerSchema } from '../types';
+/** Schema 的使用场景 */
+export type SchemaUsage = 'neutral' | 'request' | 'response';
+/** 对象属性类型覆盖 */
+export type SchemaPropertyOverrides = Record<string, string>;
+/**
+ * 判断字符串是否为合法 TypeScript 标识符
+ * @param name 属性名
+ * @returns 是否为合法标识符
+ */
+export declare function isValidIdentifier(name: string): boolean;
+/**
+ * 格式化 TypeScript 属性名
+ * @param name 属性名
+ * @returns 可用于类型声明的属性名
+ */
+export declare function formatTsPropertyName(name: string): string;
+/**
+ * 转义 JSDoc 文本
+ * @param text 原始文本
+ * @returns 可安全写入单行 JSDoc 的文本
+ */
+export declare function escapeJSDocText(text: string): string;
+/**
+ * 移除联合类型中的顶层 null 类型
+ * @param typeStr 类型字符串
+ * @returns 移除 null 后的类型字符串
+ */
+export declare function stripNullFromUnion(typeStr: string): string;
+/**
+ * 判断 Schema 是否应按对象处理
+ * @param schema OpenAPI Schema
+ * @returns 是否为对象 Schema
+ */
+export declare function isObjectSchema(schema: SwaggerSchema): boolean;
+/**
+ * 判断 Schema 是否为项目约定的泛型响应容器
+ * @param schema OpenAPI Schema
+ * @returns 是否为泛型响应容器
+ */
+export declare function isGenericResponseSchema(schema: SwaggerSchema): boolean;
+/**
+ * 获取当前使用场景可见的对象属性
+ * @param schema OpenAPI Schema
+ * @param usage Schema 使用场景
+ * @returns 可见属性数组
+ */
+export declare function getVisibleSchemaProperties(schema: SwaggerSchema, usage?: SchemaUsage): Array<[string, SwaggerSchema]>;
+/**
+ * 判断 Schema 在指定场景下是否需要独立类型
+ * @param schema OpenAPI Schema
+ * @param schemas 全部组件 Schema
+ * @param usage Schema 使用场景
+ * @returns 是否需要独立类型
+ */
+export declare function schemaNeedsUsageVariant(schema: SwaggerSchema, schemas: Record<string, SwaggerSchema>, usage: Exclude<SchemaUsage, 'neutral'>): boolean;
+/**
+ * 渲染对象类型成员
+ * @param schema OpenAPI Schema
+ * @param schemas 全部组件 Schema
+ * @param usage Schema 使用场景
+ * @param overrides 属性类型覆盖
+ * @returns 对象成员代码
+ */
+export declare function renderObjectMembers(schema: SwaggerSchema, schemas?: Record<string, SwaggerSchema>, usage?: SchemaUsage, overrides?: SchemaPropertyOverrides): string;
+/**
+ * 将 OpenAPI Schema 转换为 TypeScript 类型
+ * @param schema OpenAPI Schema
+ * @param schemas 全部组件 Schema
+ * @param usage Schema 使用场景
+ * @returns TypeScript 类型字符串
+ */
+export declare function swaggerTypeToTsType(schema: SwaggerSchema | undefined | null, schemas?: Record<string, SwaggerSchema>, usage?: SchemaUsage): string;
+/**
+ * 从 $ref 字符串中提取并解码引用名称
+ * @param ref OpenAPI $ref 字符串
+ * @returns 引用名称
+ */
+export declare function getRefName(ref: string): string;