jszy-swagger-doc-generator 1.1.1 → 1.4.1

package/dist/index.js

@@ -287,7 +287,7 @@ class SwaggerDocGenerator {
         return `export type ${typeName} = ${convertTypeToTs(schema, allSchemas)};\n`;
     }
     /**
-     * Generates React hooks from the paths in Swagger doc
+     * Generates React hooks from the paths in Swagger doc organized by tag
      */
     generateReactHooks(swaggerDoc) {
         const hooksByTag = new Map();
@@ -304,10 +304,65 @@ class SwaggerDocGenerator {
                 endpointsByTag[tag].push({ path, method, endpointInfo });
             });
         });
-        // Generate hooks for each tag
+        // Generate hooks and types for each tag
         Object.entries(endpointsByTag).forEach(([tag, endpoints]) => {
-            let tagContent = this.generateHeaderForTag(tag);
-            // Generate all parameter interfaces for this tag first to avoid duplicates
+            // Generate TypeScript types for schemas used in this tag
+            let typesContent = `// ${toPascalCase(tag)} API Types\n\n`;
+            // First, find all directly used schemas in endpoints for this tag
+            const directlyUsedSchemas = new Set();
+            if (schemas) {
+                Object.entries(schemas).forEach(([typeName, schema]) => {
+                    if (this.isSchemaUsedInEndpoints(typeName, endpoints, schemas)) {
+                        directlyUsedSchemas.add(typeName);
+                    }
+                });
+            }
+            // Then, find all referenced schemas (schemas that are referenced by the directly used ones)
+            const allNeededSchemas = this.findAllReferencedSchemas(directlyUsedSchemas, schemas);
+            // Generate types for all needed schemas
+            if (schemas) {
+                for (const typeName of allNeededSchemas) {
+                    const schema = schemas[typeName];
+                    if (schema) {
+                        typesContent += this.generateSingleTypeDefinition(typeName, schema, schemas);
+                        typesContent += '\n';
+                    }
+                }
+            }
+            // Generate hooks content
+            let hooksContent = `// ${toPascalCase(tag)} API Hooks\n`;
+            hooksContent += `import { useQuery, useMutation, useQueryClient } from 'react-query';\n`;
+            hooksContent += `import axios from 'axios';\n`;
+            // Determine which types are actually used in this tag's endpoints and generate imports
+            const usedTypeNames = new Set();
+            // First, find all types that are directly used in endpoints for this tag
+            if (schemas) {
+                for (const [typeName, schema] of Object.entries(schemas)) {
+                    if (this.isSchemaUsedInEndpoints(typeName, endpoints, schemas)) {
+                        usedTypeNames.add(typeName);
+                    }
+                }
+            }
+            // Then, add all transitive dependencies of the directly used types
+            const finalTypeNames = new Set();
+            for (const typeName of usedTypeNames) {
+                finalTypeNames.add(typeName);
+                // Find all types referenced by this type
+                const referencedTypes = this.findSchemaReferences(schemas[typeName], schemas);
+                for (const refName of referencedTypes) {
+                    if (schemas[refName]) {
+                        finalTypeNames.add(refName);
+                    }
+                }
+            }
+            // Add import statement only if there are types to import
+            if (finalTypeNames.size > 0) {
+                hooksContent += `import type { ${Array.from(finalTypeNames).join(', ')} } from './${toCamelCase(tag)}.types';\n\n`;
+            }
+            else {
+                hooksContent += `\n`;
+            }
+            // Generate parameter interfaces for this tag
             const allParamInterfaces = [];
             endpoints.forEach(({ path, method, endpointInfo }) => {
                 const paramInterface = this.generateParamInterface(path, method, endpointInfo, schemas);
@@ -317,22 +372,176 @@ class SwaggerDocGenerator {
             });
             // Add all unique parameter interfaces
             allParamInterfaces.forEach(interfaceCode => {
-                tagContent += interfaceCode + '\n';
+                hooksContent += interfaceCode + '\n';
             });
-            // Generate individual hooks
+            // Generate individual hooks using react-query and axios
             endpoints.forEach(({ path, method, endpointInfo }) => {
-                const hookContent = this.generateSingleHookWithUniqueName(path, method, endpointInfo, schemas);
-                tagContent += hookContent + '\n';
+                const hookContent = this.generateReactQueryHook(path, method, endpointInfo, schemas);
+                hooksContent += hookContent + '\n';
             });
-            hooksByTag.set(tag, tagContent);
+            hooksByTag.set(tag, { hooks: hooksContent, types: typesContent });
         });
         return hooksByTag;
     }
     /**
-     * Generates header content for a specific tag
+     * Checks if a schema is used in any of the endpoints
+     */
+    isSchemaUsedInEndpoints(schemaName, endpoints, allSchemas) {
+        for (const { endpointInfo } of endpoints) {
+            // Check if schema is used as response
+            if (endpointInfo.responses) {
+                for (const [, responseInfo] of Object.entries(endpointInfo.responses)) {
+                    if (responseInfo.content) {
+                        for (const [, contentInfo] of Object.entries(responseInfo.content)) {
+                            if (contentInfo.schema) {
+                                if (this.schemaContainsRef(contentInfo.schema, schemaName, allSchemas)) {
+                                    return true;
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+            // Check if schema is used in parameters
+            if (endpointInfo.parameters) {
+                for (const param of endpointInfo.parameters) {
+                    if (param.schema && this.schemaContainsRef(param.schema, schemaName, allSchemas)) {
+                        return true;
+                    }
+                }
+            }
+            // Check if schema is used in request body
+            if (endpointInfo.requestBody && endpointInfo.requestBody.content) {
+                for (const [, contentInfo] of Object.entries(endpointInfo.requestBody.content)) {
+                    if (contentInfo.schema && this.schemaContainsRef(contentInfo.schema, schemaName, allSchemas)) {
+                        return true;
+                    }
+                }
+            }
+        }
+        return false;
+    }
+    /**
+     * Checks if a schema contains a reference to another schema
+     */
+    schemaContainsRef(schema, targetSchemaName, allSchemas) {
+        if (!schema)
+            return false;
+        // Check if this schema directly references the target
+        if (schema.$ref) {
+            const refTypeName = schema.$ref.split('/').pop();
+            if (refTypeName === targetSchemaName) {
+                return true;
+            }
+        }
+        // Recursively check nested properties
+        if (schema.properties) {
+            for (const [, propSchema] of Object.entries(schema.properties)) {
+                if (this.schemaContainsRef(propSchema, targetSchemaName, allSchemas)) {
+                    return true;
+                }
+            }
+        }
+        // Check if it's an array schema
+        if (schema.items) {
+            if (this.schemaContainsRef(schema.items, targetSchemaName, allSchemas)) {
+                return true;
+            }
+        }
+        // Check allOf, oneOf, anyOf
+        if (schema.allOf) {
+            for (const item of schema.allOf) {
+                if (this.schemaContainsRef(item, targetSchemaName, allSchemas)) {
+                    return true;
+                }
+            }
+        }
+        if (schema.oneOf) {
+            for (const item of schema.oneOf) {
+                if (this.schemaContainsRef(item, targetSchemaName, allSchemas)) {
+                    return true;
+                }
+            }
+        }
+        if (schema.anyOf) {
+            for (const item of schema.anyOf) {
+                if (this.schemaContainsRef(item, targetSchemaName, allSchemas)) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+    /**
+     * Find all referenced schemas from a set of directly used schemas
+     */
+    findAllReferencedSchemas(initialSchemas, allSchemas) {
+        const result = new Set([...initialSchemas]); // Start with initial schemas
+        let changed = true;
+        while (changed) {
+            changed = false;
+            for (const typeName of [...result]) { // Use spread to create a new array to avoid concurrent modification
+                const schema = allSchemas[typeName];
+                if (schema) {
+                    // Check for references in the schema
+                    const referencedSchemas = this.findSchemaReferences(schema, allSchemas);
+                    for (const refName of referencedSchemas) {
+                        if (!result.has(refName) && allSchemas[refName]) {
+                            result.add(refName);
+                            changed = true;
+                        }
+                    }
+                }
+            }
+        }
+        return result;
+    }
+    /**
+     * Find schema references in a given schema
      */
-    generateHeaderForTag(tag) {
-        return `// ${toPascalCase(tag)} API Hooks\n\n`;
+    findSchemaReferences(schema, allSchemas) {
+        const references = new Set();
+        if (!schema)
+            return references;
+        // Check direct $ref
+        if (schema.$ref) {
+            const refTypeName = schema.$ref.split('/').pop();
+            if (refTypeName && allSchemas[refTypeName]) {
+                references.add(refTypeName);
+            }
+        }
+        // Check properties
+        if (schema.properties) {
+            Object.values(schema.properties).forEach((propSchema) => {
+                const nestedRefs = this.findSchemaReferences(propSchema, allSchemas);
+                nestedRefs.forEach(ref => references.add(ref));
+            });
+        }
+        // Check array items
+        if (schema.items) {
+            const itemRefs = this.findSchemaReferences(schema.items, allSchemas);
+            itemRefs.forEach(ref => references.add(ref));
+        }
+        // Check allOf, oneOf, anyOf
+        if (schema.allOf) {
+            schema.allOf.forEach((item) => {
+                const itemRefs = this.findSchemaReferences(item, allSchemas);
+                itemRefs.forEach(ref => references.add(ref));
+            });
+        }
+        if (schema.oneOf) {
+            schema.oneOf.forEach((item) => {
+                const itemRefs = this.findSchemaReferences(item, allSchemas);
+                itemRefs.forEach(ref => references.add(ref));
+            });
+        }
+        if (schema.anyOf) {
+            schema.anyOf.forEach((item) => {
+                const itemRefs = this.findSchemaReferences(item, allSchemas);
+                itemRefs.forEach(ref => references.add(ref));
+            });
+        }
+        return references;
     }
     /**
      * Generates a parameter interface for an API endpoint
@@ -348,7 +557,22 @@ class SwaggerDocGenerator {
         }
         // Create a unique interface name based on the operation ID
         const operationId = endpointInfo.operationId || this.generateOperationId(path, method);
-        const interfaceName = `${toPascalCase(operationId)}Params`;
+        // Extract action name from operationId to create cleaner parameter interface names
+        // e.g. configController_updateConfig -> UpdateConfigParams instead of ConfigController_updateConfigParams
+        let interfaceName;
+        if (operationId.includes('_')) {
+            const parts = operationId.split('_');
+            if (parts.length >= 2) {
+                // Use just the action part in the interface name
+                interfaceName = `${toPascalCase(parts[parts.length - 1])}Params`;
+            }
+            else {
+                interfaceName = `${toPascalCase(operationId)}Params`;
+            }
+        }
+        else {
+            interfaceName = `${toPascalCase(operationId)}Params`;
+        }
         let paramsInterface = `export interface ${interfaceName} {\n`;
         // Add path parameters
         pathParams.forEach((param) => {
@@ -366,24 +590,29 @@ class SwaggerDocGenerator {
         return paramsInterface;
     }
     /**
-     * Generates a single React hook for an API endpoint with unique parameter interface
+     * Generates a React Query hook using axios
      */
-    generateSingleHookWithUniqueName(path, method, endpointInfo, schemas) {
+    generateReactQueryHook(path, method, endpointInfo, schemas) {
         const operationId = endpointInfo.operationId || this.generateOperationId(path, method);
-        const hookName = `use${toPascalCase(operationId)}`;
+        // Extract action name from operationId to create cleaner hook names
+        // e.g. configController_updateConfig -> useUpdateConfig instead of useConfigController_updateConfig
+        let hookName = `use${toPascalCase(operationId)}`;
+        // Check if operationId follows pattern controller_action and simplify to action
+        if (operationId.includes('_')) {
+            const parts = operationId.split('_');
+            if (parts.length >= 2) {
+                // Use just the action part as the hook name
+                hookName = `use${toPascalCase(parts[parts.length - 1])}`;
+            }
+        }
+        else {
+            // For operationIds without underscores, keep the original naming
+            hookName = `use${toPascalCase(operationId)}`;
+        }
+        const hookType = method.toLowerCase() === 'get' ? 'useQuery' : 'useMutation';
         // Use unique parameter interface name
         const pathParams = endpointInfo.parameters?.filter((p) => p.in === 'path') || [];
         const queryParams = endpointInfo.parameters?.filter((p) => p.in === 'query') || [];
-        let paramsDeclaration = '';
-        let paramsUsage = '{}';
-        const hasParams = pathParams.length > 0 || queryParams.length > 0;
-        if (hasParams) {
-            const paramInterfaceName = `${toPascalCase(operationId)}Params`;
-            paramsDeclaration = `params: ${paramInterfaceName}`;
-            paramsUsage = 'params';
-        }
-        // Format the path for use in the code (handle path parameters)
-        const pathWithParams = path.replace(/{(\w+)}/g, (_, param) => `\${params.${toCamelCase(param)}}`);
         // Determine response type
         let responseType = 'any';
         if (endpointInfo.responses && endpointInfo.responses['200']) {
@@ -393,60 +622,145 @@ class SwaggerDocGenerator {
             }
         }
         // Generate request body parameter if needed
-        let requestBodyParam = '';
+        let requestBodyType = 'any';
+        let hasBody = false;
         if (method.toLowerCase() !== 'get' && method.toLowerCase() !== 'delete' && endpointInfo.requestBody) {
             const bodySchema = endpointInfo.requestBody.content?.['application/json']?.schema;
             if (bodySchema) {
-                const bodyType = convertTypeToTs(bodySchema, schemas);
-                requestBodyParam = `, body: ${bodyType}`;
+                requestBodyType = convertTypeToTs(bodySchema, schemas);
+                hasBody = true;
             }
         }
-        // Create the hook function
-        let hookCode = `export const ${hookName} = () => {\n`;
-        hookCode += `  const apiCall = async (${paramsDeclaration}${requestBodyParam ? requestBodyParam : ''}) => {\n`;
-        hookCode += `    const path = \`\${process.env.REACT_APP_API_BASE_URL || ''}${pathWithParams}\`;\n`;
-        // Add query parameters
-        if (endpointInfo.parameters && endpointInfo.parameters.some((p) => p.in === 'query')) {
-            hookCode += `    const queryParams = new URLSearchParams();\n`;
-            endpointInfo.parameters.forEach((param) => {
-                if (param.in === 'query') {
-                    hookCode += `    if (params.${toCamelCase(param.name)}) queryParams.append('${param.name}', params.${toCamelCase(param.name)}.toString());\n`;
-                }
-            });
-            hookCode += `    const queryString = queryParams.toString();\n`;
-            hookCode += `    const url = \`\${path}\${queryString ? '?' + queryString : ''}\`;\n`;
+        // Format the path for use in the code (handle path parameters) - without base URL
+        const formattedPath = path.replace(/{(\w+)}/g, (_, param) => `\${params.${toCamelCase(param)}}`);
+        const axiosPath = `\`${formattedPath}\``;
+        // Generate the hook code
+        let hookCode = '';
+        if (method.toLowerCase() === 'get') {
+            // For GET requests, use useQuery
+            const hasParams = pathParams.length > 0 || queryParams.length > 0;
+            if (hasParams) {
+                // Generate simpler parameter interface name based on hook name instead of operationId
+                const paramInterfaceName = `${hookName.replace('use', '')}Params`;
+                hookCode += `export const ${hookName} = (params: ${paramInterfaceName}) => {\n`;
+                hookCode += `  return useQuery({\n`;
+                hookCode += `    queryKey: ['${operationId}', params],\n`;
+                hookCode += `    queryFn: async () => {\n`;
+                hookCode += `      const response = await axios.get<${responseType}>(${axiosPath}, { params });\n`;
+                hookCode += `      return response.data;\n`;
+                hookCode += `    },\n`;
+                hookCode += `  });\n`;
+                hookCode += `};\n`;
+            }
+            else {
+                hookCode += `export const ${hookName} = () => {\n`;
+                hookCode += `  return useQuery({\n`;
+                hookCode += `    queryKey: ['${operationId}'],\n`;
+                hookCode += `    queryFn: async () => {\n`;
+                hookCode += `      const response = await axios.get<${responseType}>(${axiosPath});\n`;
+                hookCode += `      return response.data;\n`;
+                hookCode += `    },\n`;
+                hookCode += `  });\n`;
+                hookCode += `};\n`;
+            }
         }
         else {
-            hookCode += `    const url = path;\n`;
-        }
-        // Add fetch options
-        hookCode += `    const options: RequestInit = {\n`;
-        hookCode += `      method: '${method.toUpperCase()}',\n`;
-        if (requestBodyParam) {
-            hookCode += `      headers: {\n        'Content-Type': 'application/json',\n      },\n`;
-            hookCode += `      body: JSON.stringify(body),\n`;
-        }
-        hookCode += `    };\n\n`;
-        hookCode += `    const result = await fetch(url, options);\n`;
-        hookCode += `    return result.json() as Promise<${responseType}>;\n`;
-        hookCode += `  };\n\n`;
-        hookCode += `  return { ${toCamelCase(operationId)}: apiCall };\n`;
-        hookCode += `};\n`;
+            // For non-GET requests, use useMutation
+            const hasPathParams = pathParams.length > 0;
+            if (hasPathParams) {
+                // Generate simpler parameter interface name based on hook name instead of operationId
+                const paramInterfaceName = `${hookName.replace('use', '')}Params`;
+                hookCode += `export const ${hookName} = () => {\n`;
+                hookCode += `  const queryClient = useQueryClient();\n\n`;
+                hookCode += `  return useMutation({\n`;
+                hookCode += `    mutationFn: async ({ params, data }: { params: ${paramInterfaceName}; data: ${requestBodyType} }) => {\n`;
+                hookCode += `      const response = await axios.${method.toLowerCase()}<${responseType}>(${axiosPath}, data);\n`;
+                hookCode += `      return response.data;\n`;
+                hookCode += `    },\n`;
+                hookCode += `    onSuccess: () => {\n`;
+                hookCode += `      // Invalidate and refetch related queries\n`;
+                hookCode += `      queryClient.invalidateQueries({ queryKey: ['${operationId}'] });\n`;
+                hookCode += `    },\n`;
+                hookCode += `  });\n`;
+                hookCode += `};\n`;
+            }
+            else {
+                hookCode += `export const ${hookName} = () => {\n`;
+                hookCode += `  const queryClient = useQueryClient();\n\n`;
+                hookCode += `  return useMutation({\n`;
+                hookCode += `    mutationFn: async (data: ${requestBodyType}) => {\n`;
+                hookCode += `      const response = await axios.${method.toLowerCase()}<${responseType}>(${axiosPath}, data);\n`;
+                hookCode += `      return response.data;\n`;
+                hookCode += `    },\n`;
+                hookCode += `    onSuccess: () => {\n`;
+                hookCode += `      // Invalidate and refetch related queries\n`;
+                hookCode += `      queryClient.invalidateQueries({ queryKey: ['${operationId}'] });\n`;
+                hookCode += `    },\n`;
+                hookCode += `  });\n`;
+                hookCode += `};\n`;
+            }
+        }
         return hookCode;
     }
-    /**
-     * Generates a single React hook for an API endpoint
-     */
-    generateSingleHook(path, method, endpointInfo, schemas) {
-        // This method is kept for backward compatibility
-        return this.generateSingleHookWithUniqueName(path, method, endpointInfo, schemas);
-    }
     /**
      * Generate operation ID from path and method if not provided
      */
     generateOperationId(path, method) {
         return `${method.toLowerCase()}_${path.replace(/[\/{}]/g, '_')}`;
     }
+    /**
+     * Formats code using Prettier - sync version with child process
+     */
+    formatCode(code, filepath) {
+        // Skip formatting in test environment to avoid ESM issues
+        if (process.env.NODE_ENV === 'test' || typeof jest !== 'undefined') {
+            return code;
+        }
+        try {
+            // Use execSync to run prettier as a separate process to avoid ESM issues
+            const { execSync } = require('child_process');
+            const { writeFileSync, readFileSync, unlinkSync } = require('fs');
+            const { join, extname } = require('path');
+            const { tmpdir } = require('os');
+            // Determine the file extension to use for the temp file
+            const fileExtension = extname(filepath) || '.txt';
+            const tempPath = join(tmpdir(), `prettier-tmp-${Date.now()}-${Math.random().toString(36).substr(2, 9)}${fileExtension}`);
+            writeFileSync(tempPath, code, 'utf8');
+            // Format the file using prettier CLI
+            execSync(`npx prettier --write "${tempPath}" --single-quote --trailing-comma es5 --tab-width 2 --semi --print-width 80`, {
+                stdio: 'pipe'
+            });
+            // Read the formatted content back
+            const formattedCode = readFileSync(tempPath, 'utf8');
+            // Clean up the temporary file
+            unlinkSync(tempPath);
+            return formattedCode;
+        }
+        catch (error) {
+            console.warn(`Failed to format ${filepath} with Prettier:`, error);
+            return code; // Return unformatted code if formatting fails
+        }
+    }
+    /**
+     * Gets the parser based on file extension
+     */
+    getParserForFile(filepath) {
+        const ext = path.extname(filepath);
+        switch (ext) {
+            case '.ts':
+            case '.tsx':
+                return 'typescript';
+            case '.js':
+            case '.jsx':
+                return 'babel';
+            case '.json':
+                return 'json';
+            case '.md':
+                return 'markdown';
+            default:
+                return 'typescript';
+        }
+    }
     /**
      * Saves the generated documentation to a file
      */
@@ -455,7 +769,8 @@ class SwaggerDocGenerator {
         if (!fs.existsSync(dir)) {
             fs.mkdirSync(dir, { recursive: true });
         }
-        fs.writeFileSync(outputPath, documentation, 'utf8');
+        const formattedDocumentation = this.formatCode(documentation, outputPath);
+        fs.writeFileSync(outputPath, formattedDocumentation, 'utf8');
     }
     /**
      * Saves the generated TypeScript types to a file
@@ -465,7 +780,8 @@ class SwaggerDocGenerator {
         if (!fs.existsSync(dir)) {
             fs.mkdirSync(dir, { recursive: true });
         }
-        fs.writeFileSync(outputPath, types, 'utf8');
+        const formattedTypes = this.formatCode(types, outputPath);
+        fs.writeFileSync(outputPath, formattedTypes, 'utf8');
     }
     /**
      * Saves the generated React hooks to files organized by tag
@@ -475,13 +791,21 @@ class SwaggerDocGenerator {
         if (!fs.existsSync(dir)) {
             fs.mkdirSync(dir, { recursive: true });
         }
-        for (const [tag, content] of hooksByTag) {
+        for (const [tag, { hooks, types }] of hooksByTag) {
             const tagDir = path.join(outputDir, toCamelCase(tag));
             if (!fs.existsSync(tagDir)) {
                 fs.mkdirSync(tagDir, { recursive: true });
             }
-            const fileName = path.join(tagDir, `${toCamelCase(tag)}.hooks.ts`);
-            fs.writeFileSync(fileName, content, 'utf8');
+            // Save hooks to hooks file
+            const hooksFileName = path.join(tagDir, `${toCamelCase(tag)}.hooks.ts`);
+            const formattedHooks = this.formatCode(hooks, hooksFileName);
+            fs.writeFileSync(hooksFileName, formattedHooks, 'utf8');
+            // Save types to types file
+            if (types.trim()) { // Only save if there are types
+                const typesFileName = path.join(tagDir, `${toCamelCase(tag)}.types.ts`);
+                const formattedTypes = this.formatCode(types, typesFileName);
+                fs.writeFileSync(typesFileName, formattedTypes, 'utf8');
+            }
         }
     }
 }