swaggerjsontoapidocs 1.9.0 → 1.10.1

package/README.md

@@ -46,153 +46,158 @@ MSYS_NO_PATHCONV=1 npx swaggerjsontoapidocs [options]
 ### 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" }
+        }
       }
     }
   }
@@ -204,46 +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
- * @param categoryId
- */
-export const products_id_category_categoryId = (id: any, categoryId: 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
- * @param categoryId
- */
-export const products_id_category_categoryid = (id: any, categoryId: 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:
@@ -254,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

@@ -52,7 +52,7 @@ const argv = (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
     .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;

package/bin/jsonToApiDocs.js

@@ -49,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;
@@ -82,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 });
@@ -106,7 +106,8 @@ const getFilePath = (folder) => {
         : `${mainFolderOutPut}/${folder}/${folder}${ext}`;
 };
 function normalizeEndpoint(endpoint, toLowercase) {
-    const name = endpoint
+    const endpointCleaned = endpoint.replace(/[^a-zA-Z0-9_$/]/g, '');
+    const name = endpointCleaned
         .split('/')
         .map((value) => {
         if (value.startsWith('{')) {
@@ -134,21 +135,31 @@ const generateDocumentation = (endpoint, methods, apiEndpoint) => {
     })
         .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,
@@ -167,15 +178,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}`, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swaggerjsontoapidocs",
-  "version": "1.9.0",
+  "version": "1.10.1",
   "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"