swaggerjsontoapidocs 1.8.0 → 1.10.0

package/README.md

@@ -36,162 +36,168 @@ MSYS_NO_PATHCONV=1 npx swaggerjsontoapidocs [options]
 
 ### Available Arguments
 
-- `-s, --swagger <url>`: Specifies the URL of the Swagger JSON file.
-- `--bp <path>`: Base path to remove from endpoints (e.g., `/api/`).
-- `-o, --output <path>`: Path to the output folder destination.
-- `--skip-folder`: Generates flat files instead of nested folders.
-- `--fnl, --function-name-lowercase`: Force all function names to lowercase for consistency.
+- `-s, --swagger <url>` : URL of the Swagger/OpenAPI JSON (required).
+- `--bp <path>` : Base path to remove from endpoints (e.g. `/api/`) (required).
+- `-o, --output <path>` : Destination folder for generated files (optional).
+- `--skip-folder` : Generate flat files (no nested folders).
+- `--fnl` : Force function names to lowercase.
+- `-e, --ext <.ts|.js>` : Output file extension for generated files. Allowed values: `.ts` (default) or `.js`.
 
 ### Example Usage
 
 ```bash
-npx swaggerjsontoapidocs -s http://localhost:5033/swagger/v1/swagger.json --bp /api/
+npx swaggerjsontoapidocs -s http://localhost:5033/swagger/v1/swagger.json --bp /api/v1/
 ```
 
 In this example:
 
 - `-s` points to the URL of the Swagger JSON file.
-- `--bp` defines the base path `/api/` to be removed from the endpoints.
+- `--bp` defines the base path `/api/v1/` to be removed from the endpoints.
 
 <details>
   <summary>Swagger.json (Click to expand)</summary>
 
 ```json
 {
-  "openapi": "3.0.1",
+  "swagger": "2.0",
   "info": {
-    "title": "fakeApi",
-    "version": "1.0"
+    "version": "1.2.0",
+    "title": "Extended Sample API with Multiple Path Parameters",
+    "description": "Test Swagger specification including endpoints with multiple path parameters."
   },
   "paths": {
-    "/api/Users": {
+    "/api/v1/users/{userId}/orders/{orderId}": {
       "get": {
-        "tags": ["Users"],
-        "responses": {
-          "200": {
-            "description": "OK",
-            "content": {
-              "text/plain": {
-                "schema": {
-                  "type": "array",
-                  "items": {
-                    "$ref": "#/components/schemas/Usuario"
-                  }
-                }
-              },
-              "application/json": {
-                "schema": {
-                  "type": "array",
-                  "items": {
-                    "$ref": "#/components/schemas/Usuario"
-                  }
-                }
-              },
-              "text/json": {
-                "schema": {
-                  "type": "array",
-                  "items": {
-                    "$ref": "#/components/schemas/Usuario"
-                  }
-                }
-              }
-            }
+        "tags": ["Order Processing"],
+        "summary": "Get a specific order for a user",
+        "parameters": [
+          {
+            "name": "userId",
+            "in": "path",
+            "required": true,
+            "type": "string"
+          },
+          {
+            "name": "orderId",
+            "in": "path",
+            "required": true,
+            "type": "string"
           }
+        ],
+        "responses": {
+          "200": { "description": "Order details" },
+          "404": { "description": "Order not found" }
         }
+      },
+      "put": {
+        "tags": ["Order Processing"],
+        "summary": "Update a specific order for a user",
+        "parameters": [
+          {
+            "name": "userId",
+            "in": "path",
+            "required": true,
+            "type": "string"
+          },
+          {
+            "name": "orderId",
+            "in": "path",
+            "required": true,
+            "type": "string"
+          },
+          {
+            "name": "body",
+            "in": "body",
+            "required": true,
+            "schema": { "$ref": "#/definitions/Order" }
+          }
+        ],
+        "responses": { "200": { "description": "Order updated" } }
       }
     },
-    "/api/Users/{id}": {
-      "get": {
-        "tags": ["Users"],
+    "/api/v1/Products/{productId}/Reviews/{reviewId}/Comments/{commentId}": {
+      "delete": {
+        "tags": ["Reviews"],
+        "summary": "Delete a specific comment on a review",
         "parameters": [
           {
-            "name": "id",
+            "name": "productId",
             "in": "path",
             "required": true,
-            "schema": {
-              "type": "string"
-            }
+            "type": "string"
+          },
+          {
+            "name": "reviewId",
+            "in": "path",
+            "required": true,
+            "type": "string"
+          },
+          {
+            "name": "commentId",
+            "in": "path",
+            "required": true,
+            "type": "string"
           }
         ],
         "responses": {
-          "200": {
-            "description": "OK",
-            "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/Usuario"
-                }
-              },
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/Usuario"
-                }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/Usuario"
-                }
-              }
-            }
-          }
+          "200": { "description": "Comment deleted" },
+          "404": { "description": "Comment not found" }
         }
-      },
+      }
+    },
+    "/api/v1/admin/{section}/{entityId}/actions/{actionId}": {
       "post": {
-        "tags": ["Users"],
+        "tags": ["Administration"],
+        "summary": "Perform an admin action on an entity",
         "parameters": [
           {
-            "name": "id",
+            "name": "section",
+            "in": "path",
+            "required": true,
+            "type": "string"
+          },
+          {
+            "name": "entityId",
             "in": "path",
             "required": true,
+            "type": "string"
+          },
+          {
+            "name": "actionId",
+            "in": "path",
+            "required": true,
+            "type": "string"
+          },
+          {
+            "name": "body",
+            "in": "body",
+            "required": false,
             "schema": {
-              "type": "string"
+              "type": "object",
+              "properties": {
+                "reason": { "type": "string" },
+                "timestamp": { "type": "string", "format": "date-time" }
+              }
             }
           }
         ],
         "responses": {
-          "200": {
-            "description": "OK",
-            "content": {
-              "text/plain": {
-                "schema": {
-                  "$ref": "#/components/schemas/Usuario"
-                }
-              },
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/Usuario"
-                }
-              },
-              "text/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/Usuario"
-                }
-              }
-            }
-          }
+          "200": { "description": "Action executed successfully" },
+          "400": { "description": "Invalid action" }
         }
       }
     }
   },
-  "components": {
-    "schemas": {
-      "Usuario": {
-        "type": "object",
-        "properties": {
-          "id": {
-            "type": "string",
-            "nullable": true
-          },
-          "nombre": {
-            "type": "string",
-            "nullable": true
-          },
-          "email": {
-            "type": "string",
-            "nullable": true
-          }
-        },
-        "additionalProperties": false
+  "definitions": {
+    "Order": {
+      "type": "object",
+      "properties": {
+        "id": { "type": "string" },
+        "status": { "type": "string" },
+        "items": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
       }
     }
   }
@@ -203,44 +209,52 @@ In this example:
 ### Result
 
 ```bash
-├── api_docs
-│   ├── products
-│       └── products.ts
+api_docs/
+├── admin
+│   └── admin.ts
+├── products
+│   └── products.ts
+└── users
+    └── users.ts
 ```
 
 ```typescript
 // products.ts
 /**
- * @endpoint /api/products
- * @methods GET - POST
+ * ##### METHODS
+ * **DELETE**: Delete a specific comment on a review
+ *
+ * ---
+ * **Endpoint**: `/api/v1/Products/{productId}/Reviews/{reviewId}/Comments/{commentId}`
+ *
+ * ---
+ * ##### PATH PARAMETERS
+ * @param productId - any
+ * @param reviewId - any
+ * @param commentId - any
  */
-export const products = () => `products`;
-/**
- * @endpoint /api/products/{id}/category/{categoryId}
- * @methods GET - PUT - DELETE
- * @param id
- */
-export const products_id_category_categoryId = (id: any) =>
-  `products/${id}/category/${categoryId}`;
+export const Products_productId_Reviews_reviewId_Comments_commentId = (
+  productId: any,
+  reviewId: any,
+  commentId: any,
+) => `Products/${productId}/Reviews/${reviewId}/Comments/${commentId}`;
 ```
 
 ### Result --function-name-lowercase
 
 ```typescript
 // products.ts
-/**
- * @endpoint /api/products/{id}/category/{categoryId}
- * @methods GET - PUT - DELETE
- * @param id
- */
-export const products_id_category_categoryid = (id: any) =>
-  `products/${id}/category/${categoryId}`;
+export const products_productId_reviews_reviewId_comments_commentId = (
+  productId: any,
+  reviewId: any,
+  commentId: any,
+) => `Products/${productId}/Reviews/${reviewId}/Comments/${commentId}`;
 ```
 
 ### Advanced Usage
 
 ```bash
-npx swaggerjsontoapidocs -s http://localhost:5033/swagger/v1/swagger.json --bp /api/ -o ./docs/ --skip-folder
+npx swaggerjsontoapidocs -s http://localhost:5033/swagger/v1/swagger.json --bp /api/v1/ -o ./docs/ --skip-folder
 ```
 
 In this example:
@@ -251,10 +265,11 @@ In this example:
 ### Result --skip-folder
 
 ```bash
-docs
+docs/
 └── api_docs
+    ├── admin.ts
     ├── products.ts
-    └── weatherforecast.ts
+    └── users.ts
 ```
 
 ## License

package/bin/index.js

@@ -39,19 +39,27 @@ const argv = (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
         describe: 'Force all function names to lowercase for consistency',
         default: false,
     },
+    ext: {
+        alias: 'e',
+        type: 'string',
+        choices: ['.ts', '.js'],
+        describe: 'Choose generated file extension: .ts or .js',
+        default: '.ts',
+    },
 })
     .version()
     .help()
     .alias('help', 'h')
     .strict()
     .parseSync();
-async function main() {
+function main() {
     console.log(chalk_1.default.green('CONFIGURING THE SCRIPT WITH THE PROVIDED ARGUMENTS...'));
     const swaggerPath = argv.swagger;
     const basePath = argv.bp;
     const skipFolder = argv.skipFolder;
     const output = argv.output;
     const functionNameLowercase = argv.functionNameLowercase;
+    const ext = argv.ext;
     console.log(chalk_1.default.blue(`Swagger Path: ${swaggerPath}`));
     console.log(chalk_1.default.blue(`Basepath: ${basePath}`));
     if (skipFolder) {
@@ -63,13 +71,21 @@ async function main() {
     if (functionNameLowercase) {
         console.log(chalk_1.default.blue(`functionNameLowercase: ${functionNameLowercase}`));
     }
+    if (ext) {
+        console.log(chalk_1.default.blue(`file extension: ${ext}`));
+    }
     (0, node_fs_1.writeFile)(node_path_1.default.join(__dirname, 'config.json'), `{"BASEPATH": "${basePath.trim()}","PATH": "${swaggerPath.trim()}"}`, 'utf8', (err) => {
         if (err) {
             console.error(chalk_1.default.red('Error writing the configuration file:'), err);
         }
         else {
             console.log(chalk_1.default.green('Configuration file created successfully.'));
-            const params = { skipFolder, output, functionNameLowercase };
+            const params = {
+                skipFolder,
+                output,
+                functionNameLowercase,
+                ext,
+            };
             (0, jsonToApiDocs_1.initScript)(params);
         }
     });

package/bin/jsonToApiDocs.js

@@ -17,6 +17,7 @@ let paramsConfig = {
     skipFolder: false,
     output: undefined,
     functionNameLowercase: false,
+    ext: '.ts',
 };
 async function cleanFolderOutPut() {
     await (0, promises_1.rm)(mainFolderOutPut, {
@@ -48,7 +49,7 @@ async function initScript(params) {
                 chalk_1.default.red('Could not connect: The server is off or the URL is incorrect.'));
         }
         else {
-            console.log(chalk_1.default.red(`✘ unknown error: ${error}`));
+            console.log(chalk_1.default.red(`unknown error: ${error}`));
         }
         await cleanFileAndConfig();
         return null;
@@ -81,7 +82,7 @@ async function filterPathsObject() {
 async function cleanFileAndConfig() {
     await cleanFile();
     await cleanConfig();
-    console.log('🧹 Cleaned.');
+    console.log('Cleaned.');
 }
 async function cleanFile() {
     await (0, promises_1.rm)((0, node_path_1.join)(__dirname, 'paths.json'), { force: true });
@@ -99,9 +100,10 @@ async function makeFolders(foldersName) {
     }
 }
 const getFilePath = (folder) => {
+    const ext = paramsConfig.ext ?? '.ts';
     return paramsConfig.skipFolder
-        ? `${mainFolderOutPut}/${folder}.ts`
-        : `${mainFolderOutPut}/${folder}/${folder}.ts`;
+        ? `${mainFolderOutPut}/${folder}${ext}`
+        : `${mainFolderOutPut}/${folder}/${folder}${ext}`;
 };
 function normalizeEndpoint(endpoint, toLowercase) {
     const name = endpoint
@@ -126,24 +128,37 @@ const formatEndpointNames = (endpoint) => {
 const generateDocumentation = (endpoint, methods, apiEndpoint) => {
     const paramsMatch = endpoint.match(/\{([^{}]+)\}/g) || [];
     const args = paramsMatch
-        .map((p) => `${p.replace(/[{}]/g, '')}:any`)
+        .map((p) => {
+        const name = p.replace(/[{}]/g, '');
+        return paramsConfig.ext === '.ts' ? `${name}: any` : name;
+    })
         .join(', ');
     const paramsDoc = paramsMatch
-        .map((p) => `* @param ${p.replace(/[{}]/g, '')}`)
+        .map((p) => `* @param ${p.replace(/[{}]/g, '')} - any`)
         .join('\n');
-    const endpointLine = apiEndpoint ? `\n* @endpoint ${apiEndpoint}\n` : '';
+    const endpointLine = apiEndpoint
+        ? `*\n* ---\n* **Endpoint**: \`${apiEndpoint}\``
+        : '*';
     const methodsDoc = methods
-        .map((method) => {
-        let doc = '* @method ' + method.verb.toUpperCase();
-        if (method.summary) {
-            doc += ` - ${method.summary}`;
+        .map((method, index) => {
+        let doc = '* **' + method.verb.toUpperCase() + '**: ';
+        doc += method.summary ? `${method.summary}` : `without summary`;
+        if (index + 1 !== methods.length) {
+            doc += '\n*';
         }
         return doc;
     })
         .join('\n');
-    const methodsLine = methodsDoc ? `${methodsDoc}\n` : '';
-    const paramsLine = paramsDoc ? `${paramsDoc}\n` : '';
-    const jsDoc = `/**${endpointLine}${methodsLine}${paramsLine}*/\n`;
+    const methodsLine = methodsDoc ? `* ##### METHODS\n${methodsDoc}` : '*';
+    const paramsLine = paramsDoc
+        ? `*\n* ---\n* ##### PATH PARAMETERS\n${paramsDoc}`
+        : '*';
+    const jsDoc = `
+/**
+${methodsLine}
+${endpointLine}
+${paramsLine}
+*/\n`;
     return {
         args,
         jsDoc,
@@ -162,15 +177,15 @@ async function makeFileContainer(apiEndpoints, foldersName) {
         try {
             await (0, promises_1.appendFile)(filePath, line);
             await formatWithPrettier(filePath);
-            console.log(`✅ Generated: ${name}`);
+            console.log(`Generated: ${name}`);
         }
         catch (error) {
-            console.error(`❌ Error occurred while writing to ${filePath}:`, error);
+            console.error(`Error occurred while writing to ${filePath}:`, error);
         }
     }
 }
 async function destinationPath(fullPath) {
-    console.log('💾 show result --->', fullPath);
+    console.log('show result --->', fullPath);
 }
 async function moveFolderToChoosePath() {
     await (0, fs_extra_1.move)(mainFolderOutPut, `${paramsConfig.output}${folderName}`, {
@@ -180,8 +195,9 @@ async function moveFolderToChoosePath() {
 }
 async function formatWithPrettier(filePath) {
     const content = await (0, promises_1.readFile)(filePath, 'utf8');
+    const parser = filePath.endsWith('.ts') ? 'typescript' : 'babel';
     const formatted = await (0, prettier_1.format)(content, {
-        parser: 'typescript',
+        parser,
         filepath: filePath,
         semi: true,
         singleQuote: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swaggerjsontoapidocs",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "description": "script to convert swagger json to api docs, this help us to consume functions and center all endpoints in one place",
   "keywords": [
     "swagger",
@@ -31,7 +31,18 @@
     "api": "ts-node ./src/index.ts",
     "dist": "node ./bin/index.js",
     "lint": "eslint .",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "prepare": "simple-git-hooks"
+  },
+  "simple-git-hooks": {
+    "pre-commit": "npx lint-staged",
+    "commit-msg": "npx commitlint --edit $1"
+  },
+  "lint-staged": {
+    "*.{js,jsx,ts,tsx}": [
+      "prettier --write",
+      "eslint --quiet"
+    ]
   },
   "bin": {
     "swaggerjsontoapidocs": "bin/index.js"
@@ -43,6 +54,8 @@
     "yargs": "18.0.0"
   },
   "devDependencies": {
+    "@commitlint/cli": "^20.4.1",
+    "@commitlint/config-conventional": "^20.4.1",
     "@eslint/js": "9.39.2",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
@@ -54,7 +67,9 @@
     "eslint": "9.39.2",
     "globals": "17.0.0",
     "jiti": "2.6.1",
+    "lint-staged": "^16.2.7",
     "semantic-release": "^25.0.2",
+    "simple-git-hooks": "^2.13.1",
     "ts-node": "10.9.2",
     "typescript": "5.9.3",
     "typescript-eslint": "8.52.0"