swaggular 0.5.0 → 1.0.0

package/README.md

@@ -1,8 +1,10 @@
 # Swaggular
 
 A powerful tool to generate Angular services and models from Swagger/OpenAPI specifications.
-Note: Currently, it does not detects generic types or common interfaces. If you want a more
-customized version, please download the project in github and modify the templates folder.
+
+You can create a configuration file to customize the generation process.
+
+If you want a more customized version, you are invited to download the project in github and modify the project.
 
 ## Features
 
@@ -37,18 +39,74 @@ npx swaggular --input=swagger.json
 Run the generator by providing the path to your Swagger/OpenAPI file:
 
 ```bash
-swaggular --input=path/to/your/swagger.json
+swaggular --input=path/to/your/swagger.json```
+
+
+## Configuration
+
+You can configure Swaggular using CLI arguments or a configuration file (e.g., `swaggular.config.json`).
+
+### CLI Arguments (`ArgsVariables`)
+
+| Argument | Description | Default |
+| :--- | :--- | :--- |
+| `--input`, `-i` | Path to the Swagger/OpenAPI file or URL. | `swagger.json` |
+| `--output`, `-o` | Output directory for generated files. | `results` |
+| `--mode` | Grouping mode for services: `tags` or `path`. | `path` |
+| `--ignore-segments` | Comma-separated list of URL segments to ignore when generating service names. | `api` |
+| `--no-generate` | Parse the Swagger file but do not generate any output files. useful for testing. | `false` |
+| `--config` | Path to a configuration file. | `swaggular.config.json` (if exists) |
+
+### Configuration File (`SwaggularConfig`)
+
+You can create a `swaggular.config.json` file in your project root to define advanced configurations, such as custom templates, base classes for DTOs, or generic types.
+
+#### Example `swaggular.config.json`
+
+```json
+{
+  "input": "swagger.json",
+  "output": "src/app/api",
+  "groupingMode": "tags",
+  "segmentsToIgnore": ["api", "v1"],
+  "types": {
+    "extendsFrom": [
+      {
+        "name": "PagedRequestDto",
+        "type": "interface",
+        "properties": [
+          { "name": "skipCount", "type": "number", "optional": true, "comments": "" },
+          { "name": "maxResultCount", "type": "number", "optional": true, "comments": "" }
+        ],
+        "imports": []
+      }
+    ],
+    "generic": [
+      {
+        "name": "PagedResultDto",
+        "type": "interface",
+        "properties": [
+          { "name": "items", "type": "T[]", "optional": true, "comments": "" },
+          { "name": "totalCount", "type": "number", "optional": true, "comments": "" }
+        ],
+        "imports": []
+      }
+    ]
+  },
+  "templates": {
+    "service": {
+      "httpParamsHandlerImport": "import { HttpHelper } from '@shared/utils/http-helper';",
+      "httpParamsHandler": "const params = HttpHelper.toHttpParams(${params} || {});"
+    }
+  }
+}
 ```
 
-#### Options
-
-- `--input`: Path to the swagger.json file (required).
-- `--ignore-segments`: Path segments to ignore when generating service names. (comma separated)
-- `--mode`: Grouping mode. (tags or path) Default: path
-- `--no-generate`: Parse the file but don't generate the output. (For testing purposes)
-- `--output`: Path to the output folder. Default: results
+This configuration allows you to:
 
-The generated files will be available in the `results` folder.
+1. **extendsFrom**: Automatically make generated DTOs extend a base class (e.g., `PagedRequestDto`) if they share the same properties.
+2. **generic**: Automatically detect and use generic types (e.g., `PagedResultDto<T>`) instead of generating duplicate classes like `PagedResultDtoOfUser`.
+3. **templates.service.options**: Customize how HTTP parameters are handled in generated services, allowing you to use your own helper functions.
 
 ## Development
 
@@ -68,8 +126,8 @@ Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduc
 ### 🚀 Roadmap
 
 - [ ] Add TSDoc comments
-- [ ] Add function to identify common properties and generate interfaces
-- [ ] Add function to generate interfaces and services for just one path
+- [ ] Add function to identify common properties and generate interfaces without any configuration
+- [ ] Add function to generate interfaces and services for just one specific path
 
 ## License
 

package/dist/index.js

@@ -3,6 +3,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.main = main;
 const swagger_parser_1 = require("./parsers/swagger-parser");
+const location_factory_1 = require("./utils/location-factory");
 const generate_interface_1 = require("./renderers/generate-interface");
 const generate_service_1 = require("./renderers/generate-service");
 const args_1 = require("./cli/args");
@@ -18,10 +19,11 @@ async function main() {
             segmentsToIgnore: variables.segmentsToIgnore,
             ignoreVariables: true,
         });
+        const locations = (0, location_factory_1.computeLocations)();
         (0, generate_interface_1.generateInterfaces)(variables);
         (0, generate_service_1.generateServices)();
-        const interfaceFiles = (0, generate_interface_1.generateInterfacesFiles)(undefined, variables);
-        const serviceFiles = (0, generate_service_1.generateServiceFiles)(undefined, variables.templates);
+        const interfaceFiles = (0, generate_interface_1.generateInterfacesFiles)(locations, variables);
+        const serviceFiles = (0, generate_service_1.generateServiceFiles)(locations, variables.templates);
         if (variables.noGenerate) {
             console.log('Files not generated');
             return;

package/dist/renderers/generate-comments.js

@@ -20,7 +20,7 @@ function generateInterfaceComments(param) {
         comments.push(`maximum: ${param.maximum}`);
     }
     if (comments.length > 0) {
-        return `  /**\n   * ${comments.join('\n   * ')}\n   */`;
+        return `/**\n   * ${comments.join('\n   * ')}\n   */`;
     }
     return '';
 }

package/dist/renderers/generate-interface.d.ts

@@ -1,13 +1,11 @@
 import { OpenAPIV3 } from 'openapi-types';
 import { FileContent } from '../types/file-content';
-import { GroupedPath } from '../types/grouped-paths';
 import { InterfaceData, InterfaceDataProperty } from '../types/interface-data';
 import { SwaggularConfig } from '../types/config';
 export declare function parametersToIProperties(parameters: (OpenAPIV3.ParameterObject | OpenAPIV3.ReferenceObject)[]): InterfaceDataProperty[];
 export declare function propertiesToIProperties(properties: Record<string, OpenAPIV3.ReferenceObject | OpenAPIV3.SchemaObject>): InterfaceDataProperty[];
 export declare function generateInterfaces(templatesConfig?: SwaggularConfig): void;
 export declare function generateWithParameters(templatesConfig?: SwaggularConfig): void;
-export declare function computeParametersName(method: string, innerPath: string, groupedPath: GroupedPath): string;
 export declare function generateComponentsSchemas(templatesConfig?: SwaggularConfig): void;
 export declare function generateInterfacesFiles(locations?: Record<string, string[]>, templatesConfig?: SwaggularConfig): FileContent[];
 export declare function generateContent(interfaceData: InterfaceData, deep?: number): string;

package/dist/renderers/generate-interface.js

@@ -4,7 +4,6 @@ exports.parametersToIProperties = parametersToIProperties;
 exports.propertiesToIProperties = propertiesToIProperties;
 exports.generateInterfaces = generateInterfaces;
 exports.generateWithParameters = generateWithParameters;
-exports.computeParametersName = computeParametersName;
 exports.generateComponentsSchemas = generateComponentsSchemas;
 exports.generateInterfacesFiles = generateInterfacesFiles;
 exports.generateContent = generateContent;
@@ -94,6 +93,9 @@ function computeExtendsFromType(data, extendsTypes) {
         if (extendsFromTypePropertiesReq.some((p) => !dataPropertiesReq.includes(p))) {
             continue;
         }
+        if (!extendsFromType.properties.some((ep) => data.properties.some((dp) => dp.name === ep.name))) {
+            continue;
+        }
         const extensionProperties = extendsFromType.properties.map((p) => p.name.toLowerCase());
         return {
             ...data,
@@ -135,7 +137,7 @@ function generateWithParameters(templatesConfig) {
                 const properties = parametersToIProperties(parameters);
                 if (properties.length === 0)
                     continue;
-                const interfaceName = computeParametersName(httpMethod, innerPath, groupedPath);
+                const interfaceName = (0, path_utils_1.computeParametersName)(httpMethod, innerPath, groupedPath);
                 const interData = {
                     name: interfaceName,
                     type: 'interface',
@@ -152,24 +154,6 @@ function generateWithParameters(templatesConfig) {
     }
     interface_state_1.interfaceState.addInterfaces(interfacesData);
 }
-function computeParametersName(method, innerPath, groupedPath) {
-    const dict = {
-        get: '',
-        post: 'Create',
-        put: 'Update',
-        delete: 'Delete',
-        patch: 'Patch',
-    };
-    const name = dict[method];
-    const extra = (0, string_utils_1.kebabToPascalCase)((0, path_utils_1.removeVariablesFromPath)((0, path_utils_1.getExtraSegments)(innerPath, (0, path_utils_1.createBaseUrl)(groupedPath.baseSegments)).join('')));
-    // Avoid duplication if extra starts with groupName
-    let suffix = extra;
-    const groupName = groupedPath.groupName;
-    if (suffix.startsWith(groupName)) {
-        suffix = suffix.substring(groupName.length);
-    }
-    return name + groupName + (0, string_utils_1.upFirst)(suffix) + 'Params';
-}
 function generateComponentsSchemas(templatesConfig) {
     const schemas = swagger_state_1.swaggerState.getSchemas();
     if (!schemas)
@@ -305,14 +289,14 @@ function generateContent(interfaceData, deep = 0) {
             .map((p) => p.type.replace('[]', ''));
         const content = `${importsTemplate}\n\nexport interface ${interfaceData.name}${genericTypes.length > 0 ? `<${genericTypes.join(', ')}>` : ''} ${interfaceData.extendsFrom && interfaceData.extendsFrom.length > 0 ? `extends ${interfaceData.extendsFrom.join(', ')}` : ''} {
     ${interfaceData.properties
-            .map((p) => `${p.comments}\n\t${(0, string_utils_1.lowerFirst)(p.name)}${p.optional ? '?' : ''}: ${p.type};`)
+            .map((p) => `${p.comments}\n  ${(0, string_utils_1.lowerFirst)(p.name)}${p.optional ? '?' : ''}: ${p.type};`)
             .join('\n')}
   }`;
         return content;
     }
     if (interfaceData.type === 'enum') {
         const content = `export enum ${interfaceData.name} {
-    ${interfaceData.properties.map((p) => `${p.comments}\n\t${p.name} = '${p.type}',`).join('\n')}
+    ${interfaceData.properties.map((p) => `${p.comments}\n  ${p.name} = '${p.type}',`).join('\n')}
   }`;
         return content;
     }

package/dist/renderers/generate-service.js

@@ -11,7 +11,7 @@ const string_utils_1 = require("../utils/string-utils");
 const type_guard_1 = require("../utils/type-guard");
 const generate_comments_1 = require("./generate-comments");
 const object_utils_1 = require("../utils/object-utils");
-const generate_interface_1 = require("./generate-interface");
+const path_utils_2 = require("../utils/path-utils");
 const interface_state_1 = require("../core/state/interface-state");
 const template_renderer_1 = require("../utils/template-renderer");
 /**
@@ -82,13 +82,15 @@ function generateServiceFiles(locations, templatesConfig) {
             baseUrl: service.baseUrl,
             methods: methods,
             imports: allImports.join(', '),
-            modelImports: allImports.length > 0 ? `import { ${allImports.join(', ')} } from '../models';` : '',
+            modelImports: allImports.length > 0
+                ? `import { ${allImports.join(', ')} } from '${'../'.repeat(location.length)}models';`
+                : '',
             hasHttpParamsHandler: hasHttpParams,
             httpParamsHandler: serviceTemplateConfig?.options?.httpParamsHandler,
             httpParamsHandlerImport: hasHttpParams
                 ? serviceTemplateConfig?.options?.httpParamsHandlerImport
                 : '',
-            extraAngularImports: hasHttpParams ? ', HttpParams' : '',
+            extraAngularImports: hasHttpParams && !serviceTemplateConfig?.options?.httpParamsHandler ? ', HttpParams' : '',
         };
         const content = (0, template_renderer_1.renderServiceTemplate)(templatePath, templateParams);
         filesContent.push({
@@ -116,7 +118,7 @@ function buildMethods(groupedPath, pathData, serviceName) {
             const queryParams = parameters.filter((p) => p.in === 'query');
             let queryParamType;
             if (queryParams.length > 0) {
-                queryParamType = (0, generate_interface_1.computeParametersName)(method, path, groupedPath);
+                queryParamType = (0, path_utils_2.computeParametersName)(method, path, groupedPath);
             }
             const commentParams = parameters.filter((p) => p.in !== 'query');
             if (queryParamType) {
@@ -359,7 +361,7 @@ function buildMethodTemplate(method, httpParamsHandlerTemplate) {
     let paramsLogic = '';
     if (method.queryParamType) {
         if (httpParamsHandlerTemplate) {
-            paramsLogic = `\n\t\t${httpParamsHandlerTemplate.replace('${params}', 'queryParams')}`;
+            paramsLogic = `\n    ${httpParamsHandlerTemplate.replace('${params}', 'queryParams')}`;
         }
         else {
             paramsLogic = `

package/dist/types/config.d.ts

@@ -9,10 +9,6 @@ export interface SwaggularConfig {
         service?: {
             path: string;
             options?: Partial<ServiceTemplateParams>;
-            transform?: (options: ServiceTemplateParams) => string;
-            content?: string;
-            httpParamsHandler?: string;
-            httpParamsHandlerImport?: string;
         };
     };
     input?: string;

package/dist/utils/location-factory.d.ts

@@ -0,0 +1 @@
+export declare function computeLocations(): Record<string, string[]>;

package/dist/utils/location-factory.js

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeLocations = computeLocations;
+const swagger_state_1 = require("../core/state/swagger-state");
+const string_utils_1 = require("./string-utils");
+const path_utils_1 = require("./path-utils");
+function computeLocations() {
+    const swagger = swagger_state_1.swaggerState.getSwagger();
+    const groupedPaths = swagger_state_1.swaggerState.getPathsGroupedByScope();
+    const locations = {};
+    if (!swagger || !swagger.paths) {
+        return locations;
+    }
+    const processSchema = (dtoName, location) => {
+        if (locations[dtoName])
+            return;
+        if (isEnum(dtoName))
+            return;
+        locations[dtoName] = location;
+        const schemas = swagger_state_1.swaggerState.getSchemas();
+        if (!schemas || !schemas[dtoName])
+            return;
+        const schema = schemas[dtoName];
+        const refs = getReferences(schema);
+        for (const ref of refs) {
+            const childName = ref.split('/').pop();
+            if (childName) {
+                processSchema(childName, location);
+            }
+        }
+    };
+    if (groupedPaths) {
+        for (const [groupName, group] of Object.entries(groupedPaths)) {
+            if (group.baseSegments && group.baseSegments.length > 0) {
+                const folder = (0, string_utils_1.toKebabCase)(group.baseSegments[0]);
+                if (!locations[groupName]) {
+                    locations[groupName] = [folder];
+                }
+            }
+        }
+    }
+    // 1. Map Generated Parameter Interfaces
+    if (groupedPaths) {
+        for (const groupedPath of Object.values(groupedPaths)) {
+            for (const innerPath of groupedPath.paths) {
+                const pathInfo = swagger.paths[innerPath];
+                if (!pathInfo)
+                    continue;
+                const methods = ['get', 'post', 'put', 'delete', 'patch'];
+                for (const method of methods) {
+                    const operation = pathInfo[method];
+                    if (!operation)
+                        continue;
+                    // Check if parameters exist (similar condition to generate-interface)
+                    if (operation.parameters && operation.parameters.length > 0) {
+                        const interfaceName = (0, path_utils_1.computeParametersName)(method, innerPath, groupedPath);
+                        if (operation.tags && operation.tags.length > 0) {
+                            const tag = operation.tags[0];
+                            const folder = (0, string_utils_1.toKebabCase)(tag);
+                            if (!locations[interfaceName]) {
+                                locations[interfaceName] = [folder];
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    // 2. Map DTOs and Services
+    for (const pathItem of Object.values(swagger.paths)) {
+        if (!pathItem)
+            continue;
+        const operations = [
+            pathItem.get,
+            pathItem.put,
+            pathItem.post,
+            pathItem.delete,
+            pathItem.options,
+            pathItem.head,
+            pathItem.patch,
+            pathItem.trace,
+        ];
+        for (const operation of operations) {
+            if (!operation || !operation.tags || operation.tags.length === 0) {
+                continue;
+            }
+            const tag = operation.tags[0];
+            const folder = (0, string_utils_1.toKebabCase)(tag);
+            const location = [folder];
+            // Map Service (Tag) to location
+            if (!locations[tag]) {
+                locations[tag] = location;
+            }
+            // Map DTOs used in this operation
+            const refs = getReferences(operation);
+            for (const ref of refs) {
+                const dtoName = ref.split('/').pop();
+                if (dtoName) {
+                    processSchema(dtoName, location);
+                }
+            }
+        }
+    }
+    return locations;
+}
+function isEnum(name) {
+    const schemas = swagger_state_1.swaggerState.getSchemas();
+    if (!schemas)
+        return false;
+    const schema = schemas[name];
+    if (!schema)
+        return false;
+    if ('$ref' in schema)
+        return false;
+    return !!schema.enum;
+}
+function getReferences(obj) {
+    const refs = [];
+    if (!obj || typeof obj !== 'object') {
+        return refs;
+    }
+    if (Array.isArray(obj)) {
+        for (const item of obj) {
+            refs.push(...getReferences(item));
+        }
+        return refs;
+    }
+    for (const key of Object.keys(obj)) {
+        if (key === '$ref' && typeof obj[key] === 'string') {
+            refs.push(obj[key]);
+        }
+        else {
+            refs.push(...getReferences(obj[key]));
+        }
+    }
+    return refs;
+}

package/dist/utils/path-utils.d.ts

@@ -1,6 +1,8 @@
+import { GroupedPath } from '../types/grouped-paths';
 export declare function isVariable(segment: string): boolean;
 export declare function getExtraSegments(fullPath: string, baseUrl: string): string[];
 export declare function removeVariablesFromPath(path: string): string;
 export declare function createBaseUrl(baseSegments: string[]): string;
 export declare function findCommonBaseUrl(paths: string[]): string;
 export declare function standarizedPath(path: string): string;
+export declare function computeParametersName(method: string, innerPath: string, groupedPath: GroupedPath): string;

package/dist/utils/path-utils.js

@@ -6,6 +6,8 @@ exports.removeVariablesFromPath = removeVariablesFromPath;
 exports.createBaseUrl = createBaseUrl;
 exports.findCommonBaseUrl = findCommonBaseUrl;
 exports.standarizedPath = standarizedPath;
+exports.computeParametersName = computeParametersName;
+const string_utils_1 = require("./string-utils");
 function isVariable(segment) {
     return /^\{.+\}$/.test(segment);
 }
@@ -63,3 +65,21 @@ function standarizedPath(path) {
     const filtered = splitted.filter((p) => p !== '').map((p) => p.toLowerCase());
     return filtered.join('/');
 }
+function computeParametersName(method, innerPath, groupedPath) {
+    const dict = {
+        get: '',
+        post: 'Create',
+        put: 'Update',
+        delete: 'Delete',
+        patch: 'Patch',
+    };
+    const name = dict[method];
+    const extra = (0, string_utils_1.kebabToPascalCase)(removeVariablesFromPath(getExtraSegments(innerPath, createBaseUrl(groupedPath.baseSegments)).join('')));
+    // Avoid duplication if extra starts with groupName
+    let suffix = extra;
+    const groupName = groupedPath.groupName;
+    if (suffix.startsWith(groupName)) {
+        suffix = suffix.substring(groupName.length);
+    }
+    return name + groupName + (0, string_utils_1.upFirst)(suffix) + 'Params';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swaggular",
-  "version": "0.5.0",
+  "version": "1.0.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {