czh-api 1.0.0

package/src/core/parser.ts

@@ -0,0 +1,363 @@
+import { OpenAPI, OpenAPIV3 } from 'openapi-types';
+
+export interface Endpoint {
+    functionName: string;
+    description: string;
+    method: string;
+    path: string;
+    // For query and path parameters
+    requestParamsTypeName?: string;
+    // For request body
+    requestBodyTypeName?: string;
+    responseTypeName: string;
+    // List of types used to generate imports
+    referencedTypes: string[];
+    hasParams: boolean;
+    hasData: boolean;
+    contentType?: string;
+    jsdocParams: Array<{ name: string; type?: string; description?: string; required?: boolean }>;
+}
+
+export interface Module {
+    name: string;
+    endpoints: Endpoint[];
+    schemas: { [typeName: string]: OpenAPIV3.SchemaObject };
+    description?: string;
+}
+
+export type Modules = { [moduleName: string]: Module };
+
+function isReferenceObject(obj: any): obj is OpenAPIV3.ReferenceObject {
+    return obj && typeof obj.$ref === 'string';
+}
+
+function getSchemaName(ref: string): string {
+    return ref.split('/').pop() || '';
+}
+
+function addSchemaWithDependencies(name: string, module: Module, allSchemas: { [key: string]: any }) {
+    if (module.schemas[name]) {
+        return; // Already added
+    }
+
+    const schema = allSchemas[name];
+    if (!schema) {
+        return; // Schema not found
+    }
+
+    module.schemas[name] = schema as OpenAPIV3.SchemaObject;
+
+    // Recursively add dependencies
+    JSON.stringify(schema, (key, value) => {
+        if (key === '$ref' && typeof value === 'string') {
+            const depName = getSchemaName(value);
+            addSchemaWithDependencies(depName, module, allSchemas);
+        }
+        return value;
+    });
+}
+
+function getModuleName(path: string): string {
+    const parts = path.split('/').filter(p => p && !p.startsWith('{'));
+    return parts[0] || 'default';
+}
+
+function extractJsdocParamsFromSchema(schema: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject, allSchemas: { [key: string]: any }): Required<Endpoint>['jsdocParams'] {
+    const params: Required<Endpoint>['jsdocParams'] = [];
+    if (!schema) return params;
+
+    let targetSchema: OpenAPIV3.SchemaObject;
+    if (isReferenceObject(schema)) {
+        const schemaName = getSchemaName(schema.$ref);
+        targetSchema = allSchemas[schemaName] as OpenAPIV3.SchemaObject;
+    } else {
+        targetSchema = schema;
+    }
+
+    if (targetSchema?.properties) {
+        for (const propName in targetSchema.properties) {
+            const prop = targetSchema.properties[propName] as OpenAPIV3.SchemaObject;
+            
+            // 调试: 打印出当前处理的属性
+            // console.log(`正在处理属性: ${propName}`, '值为:', prop);
+
+            params.push({
+                name: propName,
+                type: prop?.type || 'any',
+                description: prop?.description || '',
+                required: targetSchema.required?.includes(propName)
+            });
+        }
+    }
+    return params;
+}
+
+function getModuleNameFromPackage(operation: OpenAPIV3.OperationObject): string | null {
+    const xPackage = (operation as any)['x-package'];
+    if (typeof xPackage === 'string' && xPackage.length > 0) {
+        const parts = xPackage.split('.');
+        const lastPart = parts[parts.length - 1];
+        // "Controller" is 10 characters
+        if (lastPart && lastPart.endsWith('Controller') && lastPart.length > 10) {
+            const rawName = lastPart.slice(0, -10);
+            return rawName.charAt(0).toLowerCase() + rawName.slice(1);
+        }
+    }
+    return null;
+}
+
+/**
+ * Processes the validated OpenAPI document into a structured format for code generation.
+ * @param api The bundled OpenAPI document.
+ * @returns A structured representation of modules and their endpoints.
+ */
+export const processApi = (api: OpenAPI.Document, excludePaths: string[] = []): Modules => {
+    const modules: Modules = {};
+    const allSchemas =  (api as OpenAPIV3.Document).components?.schemas || (api as any).definitions ||{};
+
+    const moduleFunctionNames: { [moduleName: string]: Set<string> } = {};
+
+    for (const path in api.paths) {
+        if (excludePaths.some(exclude => path.startsWith(exclude))) {
+            continue;
+        }
+
+        const pathItem = api.paths[path] as OpenAPIV3.PathItemObject;
+
+        for (const method in pathItem) {
+            // Filter for actual HTTP methods
+            if (!['get', 'post', 'put', 'delete', 'patch', 'options', 'head'].includes(method)) {
+                continue;
+            }
+
+            const operation = pathItem[method as keyof OpenAPIV3.PathItemObject] as OpenAPIV3.OperationObject;
+            if (!operation.tags) continue;
+
+            const moduleNameFromPackage = getModuleNameFromPackage(operation);
+            const moduleName = moduleNameFromPackage || getModuleName(path);
+
+            if (!modules[moduleName]) {
+                modules[moduleName] = {
+                    name: moduleName,
+                    endpoints: [],
+                    schemas: {},
+                    description: (operation.tags && operation.tags.length > 0) ? operation.tags[0] : '',
+                };
+                moduleFunctionNames[moduleName] = new Set();
+            }
+
+            // Generate function name from method and path
+            const pathParts = path.split('/').filter(p => p && !p.startsWith('{'));
+            const capitalizedPathParts = pathParts.map(part =>
+                part.split(/[._-]/)
+                    .map(subPart => subPart.charAt(0).toUpperCase() + subPart.slice(1))
+                    .join('')
+            );
+            const functionNameBase = `${method}${capitalizedPathParts.join('')}`;
+            
+            let functionName = functionNameBase;
+            let counter = 1;
+            while (moduleFunctionNames[moduleName].has(functionName)) {
+                functionName = `${functionNameBase}_${counter}`;
+                counter++;
+            }
+            moduleFunctionNames[moduleName].add(functionName);
+
+            const referencedTypes: string[] = [];
+            
+            let requestParamsTypeName: string | undefined = undefined;
+            let requestBodyTypeName: string | undefined = undefined;
+            let contentType: string | undefined = undefined;
+            const jsdocParams: Required<Endpoint>['jsdocParams'] = [];
+
+            // --- FormData Detection ---
+            let isFormData = false;
+            // Method 1: Check requestBody
+            if (operation.requestBody && !isReferenceObject(operation.requestBody)) {
+                if (operation.requestBody.content?.['multipart/form-data']) {
+                    isFormData = true;
+                }
+            }
+            // Method 2: Check for binary formats in parameters (non-standard but common)
+            if (!isFormData && operation.parameters) {
+                if (operation.parameters.some(p => {
+                    if (isReferenceObject(p)) return false;
+                    // Treat as FormData if in: 'formData' is explicitly set
+                    if (p.in === 'formData') return true;
+
+                    const schema = p.schema as OpenAPIV3.SchemaObject;
+                    // Treat as FormData if format is binary/byte (single file)
+                    if (schema?.format === 'binary' || schema?.format === 'byte') return true;
+
+                    // Treat as FormData if it's an array of binary/byte (multiple files)
+                    if (schema?.type === 'array' && ((schema.items as OpenAPIV3.SchemaObject)?.format === 'binary' || (schema.items as OpenAPIV3.SchemaObject)?.format === 'byte')) {
+                        return true;
+                    }
+
+                    return false;
+                })) {
+                    isFormData = true;
+                }
+            }
+            if (isFormData) {
+                contentType = 'multipart/form-data';
+            }
+            // --- End FormData Detection ---
+
+            // Handle All Parameters
+            if (operation.parameters) {
+                const paramsSchema: OpenAPIV3.SchemaObject = {
+                    type: 'object',
+                    properties: {},
+                    required: [],
+                };
+                // For FormData, we will build a schema for the body from query/formData parameters
+                const formDataSchema: OpenAPIV3.SchemaObject = {
+                    type: 'object',
+                    properties: {},
+                    required: [],
+                };
+
+                for (const param of operation.parameters) {
+                    if (!isReferenceObject(param)) {
+                        const paramToAdd = {
+                            name: param.name,
+                            description: param.description || '',
+                            required: param.required,
+                            type: (param.schema as any)?.type || 'any'
+                        };
+
+                        // If the parameter's schema is a reference, expand its properties
+                        if (param.in === 'query' && param.schema && isReferenceObject(param.schema)) {
+                            const schemaName = getSchemaName(param.schema.$ref);
+                            const refSchema = allSchemas[schemaName] as OpenAPIV3.SchemaObject;
+                            if (refSchema && refSchema.properties) {
+                                if(!paramsSchema.properties) paramsSchema.properties = {};
+                                Object.assign(paramsSchema.properties, refSchema.properties);
+                                if (refSchema.required) {
+                                     if(!paramsSchema.required) paramsSchema.required = [];
+                                     paramsSchema.required.push(...refSchema.required);
+                                }
+                            }
+                        } else if (isFormData && (param.in === 'query' || param.in === 'formData')) {
+                            // Collect params for the FormData body type
+                             if(!formDataSchema.properties) formDataSchema.properties = {};
+                             formDataSchema.properties[param.name] = param.schema as OpenAPIV3.SchemaObject;
+                             if(param.required) {
+                                 if(!formDataSchema.required) formDataSchema.required = [];
+                                 formDataSchema.required.push(param.name);
+                             }
+                        } else if (param.in === 'path' || param.in === 'query') {
+                            // Always collect path params
+                            if(!paramsSchema.properties) paramsSchema.properties = {};
+                            paramsSchema.properties[param.name] = param.schema as OpenAPIV3.SchemaObject;
+                            if(param.required) {
+                                if(!paramsSchema.required) paramsSchema.required = [];
+                                paramsSchema.required.push(param.name);
+                            }
+                        }
+                    }
+                }
+
+                if (isFormData && Object.keys(formDataSchema.properties || {}).length > 0) {
+                    const typeName = `${functionName.charAt(0).toUpperCase() + functionName.slice(1)}Data`;
+                    requestBodyTypeName = typeName;
+                    modules[moduleName].schemas[typeName] = formDataSchema;
+                    referencedTypes.push(typeName);
+                    jsdocParams.push(...extractJsdocParamsFromSchema(formDataSchema, allSchemas));
+                }
+
+                if (Object.keys(paramsSchema.properties || {}).length > 0) {
+                    requestParamsTypeName = `${functionName.charAt(0).toUpperCase() + functionName.slice(1)}Params`;
+                    modules[moduleName].schemas[requestParamsTypeName] = paramsSchema;
+                    referencedTypes.push(requestParamsTypeName);
+                    jsdocParams.push(...extractJsdocParamsFromSchema(paramsSchema, allSchemas));
+                }
+            }
+            
+            // Handle standard Request Body
+            if (operation.requestBody && !isReferenceObject(operation.requestBody) && !isFormData) {
+                const requestBody = operation.requestBody as OpenAPIV3.RequestBodyObject;
+                const jsonContent = requestBody.content?.['application/json'];
+
+                if (jsonContent?.schema) {
+                   if (isReferenceObject(jsonContent.schema)) {
+                        const name = getSchemaName(jsonContent.schema.$ref);
+                        requestBodyTypeName = name;
+                        addSchemaWithDependencies(name, modules[moduleName], allSchemas);
+                        referencedTypes.push(name);
+                        jsdocParams.push(...extractJsdocParamsFromSchema(jsonContent.schema, allSchemas));
+                    } else {
+                        // Handle inline schema (including arrays)
+                        const schema = jsonContent.schema as OpenAPIV3.SchemaObject;
+                        if (schema.type === 'array' || schema.type === 'object') {
+                            const typeName = `${functionName.charAt(0).toUpperCase() + functionName.slice(1)}Data`;
+                            requestBodyTypeName = typeName;
+                            modules[moduleName].schemas[typeName] = schema;
+                            referencedTypes.push(typeName);
+                            
+                            // For arrays, extract jsdoc params from array items
+                            if (schema.type === 'array' && schema.items) {
+                                if (isReferenceObject(schema.items)) {
+                                    const itemSchemaName = getSchemaName(schema.items.$ref);
+                                    addSchemaWithDependencies(itemSchemaName, modules[moduleName], allSchemas);
+                                } else {
+                                    jsdocParams.push(...extractJsdocParamsFromSchema(schema.items as OpenAPIV3.SchemaObject, allSchemas));
+                                }
+                            } else if (schema.type === 'object') {
+                                jsdocParams.push(...extractJsdocParamsFromSchema(schema, allSchemas));
+                            }
+                        }
+                    }
+                }
+            } else if (isFormData && operation.requestBody && !isReferenceObject(operation.requestBody) && !requestBodyTypeName) {
+                // Handle cases where FormData is defined in requestBody but we haven't processed it yet
+                 const formDataContent = operation.requestBody.content?.['multipart/form-data'];
+                 if (formDataContent?.schema) {
+                    const typeName = `${functionName.charAt(0).toUpperCase() + functionName.slice(1)}Data`;
+                    requestBodyTypeName = typeName;
+                    modules[moduleName].schemas[typeName] = formDataContent.schema as OpenAPIV3.SchemaObject;
+                    referencedTypes.push(typeName);
+                    jsdocParams.push(...extractJsdocParamsFromSchema(formDataContent.schema, allSchemas));
+                 }
+            }
+
+            // Handle Response Body
+            let responseTypeName = 'void';
+            const successResponse = operation.responses['200'] as OpenAPIV3.ResponseObject;
+            if(successResponse) {
+                const mediaType = successResponse.content?.['*/*'] || successResponse.content?.['application/json'];
+                const schema = mediaType?.schema;
+
+                 if (schema && isReferenceObject(schema)) {
+                    const name = getSchemaName(schema.$ref);
+                    responseTypeName = name;
+                    addSchemaWithDependencies(name, modules[moduleName], allSchemas);
+                    referencedTypes.push(name);
+                }
+            }
+
+            // Convert path to template literal string for path parameters
+            const urlTemplate = path.replace(/\{(\w+)\}/g, '${params.$1}');
+
+            const endpoint: Endpoint = {
+                functionName,
+                description: operation.summary || operation.description || '',
+                method,
+                path: urlTemplate,
+                requestParamsTypeName,
+                requestBodyTypeName,
+                responseTypeName,
+                referencedTypes: [...new Set(referencedTypes)],
+                hasParams: !!requestParamsTypeName,
+                hasData: !!requestBodyTypeName,
+                contentType,
+                jsdocParams,
+            };
+
+            modules[moduleName].endpoints.push(endpoint);
+        }
+    }
+
+    return modules;
+}; 

package/src/index.ts

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+/*
+ * @description: 
+ * @Author: czh
+ * @Date: 2025-07-02 10:39:34
+ * @LastEditors: Czh
+ * @LastEditTime: 2025-07-02 10:39:34
+ */
+import { Command } from 'commander';
+import { handleInit } from './commands/init';
+import { handleBuild } from './commands/build';
+import path from 'path';
+import fs from 'fs';
+
+const program = new Command();
+
+// Read package.json to get the version
+const packageJson = JSON.parse(fs.readFileSync(path.join(__dirname, '../package.json'), 'utf-8'));
+
+program
+    .name('czh-api')
+    .description('A CLI tool to generate API code from Swagger/OpenAPI documents.')
+    .version(packageJson.version, '-v, --version', 'output the current version');
+
+program
+    .command('init')
+    .description('Initialize czh-api and create a config file and templates.')
+    .action(handleInit);
+
+program
+    .command('build')
+    .description('Generate API code based on the configuration file.')
+    .action(handleBuild);
+
+program.parse(process.argv);
+
+if (!process.argv.slice(2).length) {
+    program.outputHelp();
+} 

package/src/templates/api.hbs

@@ -0,0 +1,23 @@
+/**
+ * @description {{description}}
+ {{#if jsdocParams}}
+ {{#each jsdocParams}}
+ * @param { {{this.type}} } {{#unless this.required}}[{{/unless}}{{this.name}}{{#unless this.required}}]{{/unless}} - {{this.description}}
+ {{/each}}
+ {{/if}}
+ */
+export const {{functionName}} = ({{#if hasParams}}params: {{requestParamsTypeName}}{{/if}}{{#if hasData}}{{#if hasParams}}, {{/if}}data: {{requestBodyTypeName}}{{/if}}) => {
+  return http.request<{{responseTypeName}}>({
+    url: `{{path}}`,
+    method: '{{method}}',
+    {{#if hasParams}}
+    params,
+    {{/if}}
+    {{#if hasData}}
+    data,
+    {{/if}}
+    {{#if contentType}}
+    headers: { 'Content-Type': '{{contentType}}' },
+    {{/if}}
+  });
+}; 

package/src/templates/index.hbs

@@ -0,0 +1,3 @@
+{{#each files}}
+export * from './{{this}}';
+{{/each}} 

package/src/templates/types.hbs

@@ -0,0 +1 @@
+{{{content}}} 

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES6",
+    "module": "CommonJS",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "node",
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "src/api", "czh-api.config.json", "czh-api-template"]
+}