swaggerjsontoapidocs 1.5.2 → 1.7.0

package/README.md

@@ -40,6 +40,7 @@ MSYS_NO_PATHCONV=1 npx swaggerjsontoapidocs [options]
 - `--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.
 
 ### Example Usage
 
@@ -203,17 +204,37 @@ In this example:
 
 ```bash
 ├── api_docs
-│   ├── Users
-│       └── Users.ts
+│   ├── products
+│       └── products.ts
 ```
 
 ```typescript
-// Users.ts
-export const Users = () => `Users`;
+// products.ts
 /**
+ * @endpoint /api/products
+ * @methods GET - POST
+ */
+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}`;
+```
+
+### Result --function-name-lowercase
+
+```typescript
+// products.ts
+/**
+ * @endpoint /api/products/{id}/category/{categoryId}
+ * @methods GET - PUT - DELETE
  * @param id
  */
-export const Users_id = (id: any) => `Users/${id}`;
+export const products_id_category_categoryid = (id: any) =>
+  `products/${id}/category/${categoryId}`;
 ```
 
 ### Advanced Usage
@@ -232,8 +253,8 @@ In this example:
 ```bash
 docs
 └── api_docs
-    ├── Users.ts
-    └── WeatherForecast.ts
+    ├── products.ts
+    └── weatherforecast.ts
 ```
 
 ## License

package/bin/index.js

@@ -4,7 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-const fs_1 = require("fs");
+const node_fs_1 = require("node:fs");
 const chalk_1 = __importDefault(require("chalk"));
 const node_path_1 = __importDefault(require("node:path"));
 const yargs_1 = __importDefault(require("yargs"));
@@ -33,6 +33,12 @@ const argv = (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
         describe: "Flat files",
         default: false,
     },
+    "function-name-lowercase": {
+        alias: "fnl",
+        type: "boolean",
+        describe: "Force all function names to lowercase for consistency",
+        default: false,
+    },
 })
     .version()
     .help()
@@ -45,6 +51,7 @@ async function main() {
     const basePath = argv.bp;
     const skipFolder = argv.skipFolder;
     const output = argv.output;
+    const functionNameLowercase = argv.functionNameLowercase;
     console.log(chalk_1.default.blue(`Swagger Path: ${swaggerPath}`));
     console.log(chalk_1.default.blue(`Basepath: ${basePath}`));
     if (skipFolder) {
@@ -53,13 +60,16 @@ async function main() {
     if (output) {
         console.log(chalk_1.default.blue(`output folder: ${output}api_docs`));
     }
-    (0, fs_1.writeFile)(node_path_1.default.join(__dirname, "config.json"), `{"BASEPATH": "${basePath.trim()}","PATH": "${swaggerPath.trim()}"}`, "utf8", (err) => {
+    if (functionNameLowercase) {
+        console.log(chalk_1.default.blue(`functionNameLowercase: ${functionNameLowercase}`));
+    }
+    (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 };
+            const params = { skipFolder, output, functionNameLowercase };
             (0, jsonToApiDocs_1.initScript)(params);
         }
     });

package/bin/jsonToApiDocs.js

@@ -4,18 +4,20 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.initScript = initScript;
-const promises_1 = require("fs/promises");
+const promises_1 = require("node:fs/promises");
 const fs_extra_1 = require("fs-extra");
-const path_1 = require("path");
+const node_path_1 = require("node:path");
 const chalk_1 = __importDefault(require("chalk"));
 const prettier_1 = require("prettier");
-const os_1 = __importDefault(require("os"));
-const child_process_1 = require("child_process");
 const folderName = "api_docs";
-const mainFolderOutPut = (0, path_1.join)(__dirname, folderName);
+const mainFolderOutPut = (0, node_path_1.join)(__dirname, folderName);
 let urlSwaggerJson = "";
 let basepath = "";
-let paramsConfig = { skipFolder: false, output: undefined };
+let paramsConfig = {
+    skipFolder: false,
+    output: undefined,
+    functionNameLowercase: false,
+};
 async function cleanFolderOutPut() {
     await (0, promises_1.rm)(mainFolderOutPut, {
         recursive: true,
@@ -25,7 +27,7 @@ async function cleanFolderOutPut() {
 async function initScript(params) {
     paramsConfig = params;
     await cleanFolderOutPut();
-    const raw = await (0, promises_1.readFile)((0, path_1.join)(__dirname, "config.json"), "utf8");
+    const raw = await (0, promises_1.readFile)((0, node_path_1.join)(__dirname, "config.json"), "utf8");
     const config = await JSON.parse(raw);
     urlSwaggerJson = config.PATH;
     basepath = config.BASEPATH;
@@ -33,7 +35,7 @@ async function initScript(params) {
         const response = await fetch(urlSwaggerJson);
         const data = await response.json();
         try {
-            await (0, promises_1.writeFile)((0, path_1.join)(__dirname, "paths.json"), `${JSON.stringify(data, null, 2)}`, "utf8");
+            await (0, promises_1.writeFile)((0, node_path_1.join)(__dirname, "paths.json"), `${JSON.stringify(data, null, 2)}`, "utf8");
             await filterPathsObject();
         }
         catch (err) {
@@ -53,17 +55,23 @@ async function initScript(params) {
     }
 }
 async function filterPathsObject() {
-    const raw = await (0, promises_1.readFile)((0, path_1.join)(__dirname, "paths.json"), "utf8");
+    const raw = await (0, promises_1.readFile)((0, node_path_1.join)(__dirname, "paths.json"), "utf8");
     const pathsObj = await JSON.parse(raw);
-    const endpoints = Object.keys(pathsObj.paths).map((endpoint) => endpoint.split(basepath)[1]);
-    const foldersName = endpoints.map((endpoint) => endpoint.split("/")[0]);
+    const regexStartWithSlash = /^\//;
+    const apiEndpoints = Object.entries(pathsObj.paths).map((path) => ({
+        endpoint: path[0].replace(basepath, "").replace(regexStartWithSlash, ""),
+        methods: Object.keys(path[1]),
+        apiEndpoint: path[0],
+    }));
+    const endpoints = apiEndpoints.map(({ endpoint }) => endpoint);
+    const foldersName = endpoints.map((endpoint) => endpoint.split("/")[0].toLocaleLowerCase());
     await makeFolders(foldersName);
-    await makeFileContainer(endpoints, foldersName);
+    await makeFileContainer(apiEndpoints, foldersName);
     if (paramsConfig.output) {
         await moveFolderToChoosePath();
     }
     else {
-        await openFileManager(mainFolderOutPut);
+        await destinationPath(mainFolderOutPut);
     }
     await cleanFileAndConfig();
 }
@@ -73,50 +81,65 @@ async function cleanFileAndConfig() {
     console.log("🧹 Cleaned.");
 }
 async function cleanFile() {
-    await (0, promises_1.rm)((0, path_1.join)(__dirname, "paths.json"), { force: true });
+    await (0, promises_1.rm)((0, node_path_1.join)(__dirname, "paths.json"), { force: true });
 }
 async function cleanConfig() {
-    await (0, promises_1.rm)((0, path_1.join)(__dirname, "config.json"), { force: true });
+    await (0, promises_1.rm)((0, node_path_1.join)(__dirname, "config.json"), { force: true });
 }
 async function makeFolders(foldersName) {
     await (0, promises_1.mkdir)(mainFolderOutPut, { recursive: true });
     if (!paramsConfig.skipFolder) {
-        for (const folder of [...new Set(foldersName)]) {
-            const folderPath = (0, path_1.join)(mainFolderOutPut, folder);
+        for (const folder of new Set(foldersName)) {
+            const folderPath = (0, node_path_1.join)(mainFolderOutPut, folder);
             await (0, promises_1.mkdir)(folderPath, { recursive: true });
         }
     }
 }
-async function makeFileContainer(endpoints, foldersName) {
-    for (const folder of [...new Set(foldersName)]) {
-        if (paramsConfig.skipFolder) {
-            await (0, promises_1.appendFile)(`${mainFolderOutPut}/${folder}.ts`, "");
-        }
-        else {
-            await (0, promises_1.appendFile)(`${mainFolderOutPut}/${folder}/${folder}.ts`, "");
-        }
+const getFilePath = (folder) => {
+    return paramsConfig.skipFolder
+        ? `${mainFolderOutPut}/${folder}.ts`
+        : `${mainFolderOutPut}/${folder}/${folder}.ts`;
+};
+function normalizeEndpoint(endpoint, toLowercase) {
+    let name = endpoint
+        .replace(/[/|{}]/g, "_")
+        .replace(/_+/g, "_")
+        .replace(/(^_)|(_$)/g, "");
+    return toLowercase ? name.toLowerCase() : name;
+}
+const formatEndpointNames = (endpoint) => {
+    const name = normalizeEndpoint(endpoint, paramsConfig.functionNameLowercase);
+    const templatePath = endpoint.replace(/\{/g, "${");
+    return { name, templatePath };
+};
+const generateDocumentation = (endpoint, methods, apiEndpoint) => {
+    const paramsMatch = endpoint.match(/\{([^{}]+)\}/g) || [];
+    const args = paramsMatch
+        .map((p) => `${p.replace(/[{}]/g, "")}:any`)
+        .join(", ");
+    const paramsDoc = paramsMatch
+        .map((p) => `* @param ${p.replace(/[{}]/g, "")}`)
+        .join("\n");
+    const endpointLine = apiEndpoint ? `\n* @endpoint ${apiEndpoint}\n` : "";
+    const methodsLine = methods
+        ? `* @methods ${methods.join(" - ").toUpperCase()}\n`
+        : "";
+    const paramsLine = paramsDoc ? `${paramsDoc}\n` : "";
+    const jsDoc = `/**${endpointLine}${methodsLine}${paramsLine}*/\n`;
+    return {
+        args,
+        jsDoc,
+    };
+};
+async function makeFileContainer(apiEndpoints, foldersName) {
+    for (const folder of new Set(foldersName)) {
+        await (0, promises_1.appendFile)(getFilePath(folder), "");
     }
     for (const [index, folder] of foldersName.entries()) {
-        const endpoint = endpoints[index];
-        const filePath = paramsConfig.skipFolder
-            ? `${mainFolderOutPut}/${folder}.ts`
-            : `${mainFolderOutPut}/${folder}/${folder}.ts`;
-        const paramsMatch = endpoint.match(/\{([^}]+)\}/g);
-        const args = paramsMatch
-            ? paramsMatch.map((p) => p.replace(/[{}]/g, "").concat(":any")).join(", ")
-            : "";
-        let jsDoc = "";
-        if (paramsMatch?.length) {
-            const paramsDoc = paramsMatch
-                .map((p) => ` * @param ${p.replace(/[{}]/g, "")}`)
-                .join("\n");
-            jsDoc = `/**\n${paramsDoc}\n */\n`;
-        }
-        const name = endpoint
-            .replace(/[/|{}]/g, "_")
-            .replace(/_+/g, "_")
-            .replace(/^_|_$/g, "");
-        const templatePath = endpoint.replace(/\{/g, "${");
+        const { endpoint, methods, apiEndpoint } = apiEndpoints[index];
+        const filePath = getFilePath(folder);
+        const { name, templatePath } = formatEndpointNames(endpoint);
+        const { args, jsDoc } = generateDocumentation(endpoint, methods, apiEndpoint);
         const line = `${jsDoc} export const ${name} = (${args}) => \`${templatePath}\`;\n`;
         try {
             await (0, promises_1.appendFile)(filePath, line);
@@ -128,31 +151,14 @@ async function makeFileContainer(endpoints, foldersName) {
         }
     }
 }
-async function openFileManager(fullPath) {
-    const platform = os_1.default.platform();
-    let command = "";
-    switch (platform) {
-        case "win32":
-            command = `explorer`;
-            break;
-        case "darwin":
-            command = `open`;
-            break;
-        case "linux":
-            command = `xdg-open`;
-            break;
-        default:
-            console.error(`Platform ${platform} is not supported.`);
-            return;
-    }
-    (0, child_process_1.exec)(`${command} "${fullPath}"`);
+async function destinationPath(fullPath) {
     console.log("💾 show result --->", fullPath);
 }
 async function moveFolderToChoosePath() {
     await (0, fs_extra_1.move)(mainFolderOutPut, `${paramsConfig.output}${folderName}`, {
         overwrite: true,
     });
-    await openFileManager((0, path_1.resolve)(`${paramsConfig.output}${folderName}`));
+    await destinationPath((0, node_path_1.resolve)(`${paramsConfig.output}${folderName}`));
 }
 async function formatWithPrettier(filePath) {
     const content = await (0, promises_1.readFile)(filePath, "utf8");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swaggerjsontoapidocs",
-  "version": "1.5.2",
+  "version": "1.7.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",