@dotflash/openapi-semantic-generator 0.1.1 → 0.1.3

package/README.md

@@ -56,8 +56,30 @@ npx openapi-semantic-generator <spec-url-or-path> -o <generated-code-dir> [optio
 
 #### Options
 
-- `-o, --output <dir>`: Directory where the code is already generated (e.g., `./src/api`)
-- `--api-dir <path>`: Relative path to APIs within the output directory (e.g., `services`)
+- `-o, --output <dir>`: **Required.** Directory where the generated code is located. This tool will scan this directory to find API files.
+  - Example: `./src/api`, `./generated/client`
+  - **Important**: The generated TypeScript files must be inside this directory or its subdirectories.
+
+- `--api-dir <path>`: Optional. Relative path from the output directory where API files are located.
+  - Example: `services`, `api`, `client/apis`
+  - This path is **relative to the `-o` directory**, not the current working directory.
+  - If not specified, the tool searches in `api/`, `apis/`, and the output directory itself (in that order).
+
+#### Usage Examples
+
+```bash
+# Basic usage: API files are in ./src/api/
+npx openapi-semantic-generator spec.yaml -o ./src/api
+
+# API files are in ./generated/services/
+npx openapi-semantic-generator spec.yaml -o ./generated --api-dir services
+
+# Using a remote spec URL
+npx openapi-semantic-generator https://api.example.com/openapi.json -o ./src/api
+
+# API files are directly in the output directory
+npx openapi-semantic-generator spec.yaml -o ./dist/client
+```
 
 ### Generated Documents
 
@@ -106,8 +128,30 @@ npx openapi-semantic-generator <spec-url-or-path> -o <generated-code-dir> [optio
 
 #### 옵션
 
-- `-o, --output <dir>`: 이미 생성된 코드가 위치한 디렉토리 (예: `./src/api`)
-- `--api-dir <path>`: 출력 디렉토리 내 API 파일이 위치한 상대 경로 (예: `services`)
+- `-o, --output <dir>`: **필수.** 생성된 코드가 위치한 디렉토리입니다. 이 도구는 해당 디렉토리를 스캔하여 API 파일을 찾습니다.
+  - 예시: `./src/api`, `./generated/client`
+  - **중요**: 생성된 TypeScript 파일이 반드시 이 디렉토리 또는 하위 디렉토리에 있어야 합니다.
+
+- `--api-dir <path>`: 선택사항. 출력 디렉토리 기준으로 API 파일이 위치한 상대 경로입니다.
+  - 예시: `services`, `api`, `client/apis`
+  - 이 경로는 **`-o` 디렉토리 기준의 상대 경로**이며, 현재 작업 디렉토리 기준이 아닙니다.
+  - 지정하지 않으면 `api/`, `apis/`, 출력 디렉토리 자체를 순서대로 검색합니다.
+
+#### 사용 예시
+
+```bash
+# 기본 사용: API 파일이 ./src/api/에 있는 경우
+npx openapi-semantic-generator spec.yaml -o ./src/api
+
+# API 파일이 ./generated/services/에 있는 경우
+npx openapi-semantic-generator spec.yaml -o ./generated --api-dir services
+
+# 원격 스펙 URL 사용
+npx openapi-semantic-generator https://api.example.com/openapi.json -o ./src/api
+
+# API 파일이 출력 디렉토리 바로 아래에 있는 경우
+npx openapi-semantic-generator spec.yaml -o ./dist/client
+```
 
 ### 생성되는 문서
 

package/dist/{chunk-IUOJNB6I.js → chunk-QEPXZXK5.js}

@@ -37,7 +37,9 @@ async function extractMetadata(specPath) {
           if (typedDetails.requestBody) {
           }
           operations.push({
-            operationId: typedDetails.operationId || `${method}_${path4.replace(/\//g, "_")}`,
+            operationId: toCamelCase(
+              typedDetails.operationId || `${method}_${path4.replace(/\//g, "_")}`
+            ),
             summary: typedDetails.summary,
             description: typedDetails.description,
             httpMethod: method.toUpperCase(),
@@ -65,6 +67,9 @@ async function extractMetadata(specPath) {
     }))
   };
 }
+function toCamelCase(str) {
+  return str.replace(/[^a-zA-Z0-9]+(.)/g, (m, chr) => chr.toUpperCase()).replace(/[^a-zA-Z0-9]/g, "");
+}
 function cleanDescription(desc) {
   if (!desc) return "";
   return desc.split("\n").filter((line) => {
@@ -95,10 +100,21 @@ async function scanGeneratedFiles(outputDir, metadata, options = {}) {
   }
   if (metadata.operations) {
     for (const op of metadata.operations) {
-      if (apis.length > 0) {
-        op.className = apis[0].className;
-        op.sourceFile = apis[0].sourceFile;
+      if (apis.length === 0) continue;
+      let matchedApi = apis[0];
+      if (op.tags && op.tags.length > 0) {
+        const primaryTag = op.tags[0].toLowerCase();
+        const normalizedTag = primaryTag.replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+        const found = apis.find((api) => {
+          const fileName = api.className.toLowerCase();
+          return fileName.includes(normalizedTag) || fileName.includes(primaryTag.replace(/\s+/g, ""));
+        });
+        if (found) {
+          matchedApi = found;
+        }
       }
+      op.className = matchedApi.className;
+      op.sourceFile = matchedApi.sourceFile;
     }
   }
   return {

package/dist/cli.cjs

@@ -75,7 +75,9 @@ async function extractMetadata(specPath) {
           if (typedDetails.requestBody) {
           }
           operations.push({
-            operationId: typedDetails.operationId || `${method}_${path5.replace(/\//g, "_")}`,
+            operationId: toCamelCase(
+              typedDetails.operationId || `${method}_${path5.replace(/\//g, "_")}`
+            ),
             summary: typedDetails.summary,
             description: typedDetails.description,
             httpMethod: method.toUpperCase(),
@@ -103,6 +105,9 @@ async function extractMetadata(specPath) {
     }))
   };
 }
+function toCamelCase(str) {
+  return str.replace(/[^a-zA-Z0-9]+(.)/g, (m, chr) => chr.toUpperCase()).replace(/[^a-zA-Z0-9]/g, "");
+}
 function cleanDescription(desc) {
   if (!desc) return "";
   return desc.split("\n").filter((line) => {
@@ -133,10 +138,21 @@ async function scanGeneratedFiles(outputDir, metadata, options = {}) {
   }
   if (metadata.operations) {
     for (const op of metadata.operations) {
-      if (apis.length > 0) {
-        op.className = apis[0].className;
-        op.sourceFile = apis[0].sourceFile;
+      if (apis.length === 0) continue;
+      let matchedApi = apis[0];
+      if (op.tags && op.tags.length > 0) {
+        const primaryTag = op.tags[0].toLowerCase();
+        const normalizedTag = primaryTag.replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+        const found = apis.find((api) => {
+          const fileName = api.className.toLowerCase();
+          return fileName.includes(normalizedTag) || fileName.includes(primaryTag.replace(/\s+/g, ""));
+        });
+        if (found) {
+          matchedApi = found;
+        }
       }
+      op.className = matchedApi.className;
+      op.sourceFile = matchedApi.sourceFile;
     }
   }
   return {

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   generateDocs
-} from "./chunk-IUOJNB6I.js";
+} from "./chunk-QEPXZXK5.js";
 
 // src/cli.ts
 import { Command } from "commander";

package/dist/index.cjs

@@ -84,7 +84,9 @@ async function extractMetadata(specPath) {
           if (typedDetails.requestBody) {
           }
           operations.push({
-            operationId: typedDetails.operationId || `${method}_${path4.replace(/\//g, "_")}`,
+            operationId: toCamelCase(
+              typedDetails.operationId || `${method}_${path4.replace(/\//g, "_")}`
+            ),
             summary: typedDetails.summary,
             description: typedDetails.description,
             httpMethod: method.toUpperCase(),
@@ -112,6 +114,9 @@ async function extractMetadata(specPath) {
     }))
   };
 }
+function toCamelCase(str) {
+  return str.replace(/[^a-zA-Z0-9]+(.)/g, (m, chr) => chr.toUpperCase()).replace(/[^a-zA-Z0-9]/g, "");
+}
 function cleanDescription(desc) {
   if (!desc) return "";
   return desc.split("\n").filter((line) => {
@@ -142,10 +147,21 @@ async function scanGeneratedFiles(outputDir, metadata, options = {}) {
   }
   if (metadata.operations) {
     for (const op of metadata.operations) {
-      if (apis.length > 0) {
-        op.className = apis[0].className;
-        op.sourceFile = apis[0].sourceFile;
+      if (apis.length === 0) continue;
+      let matchedApi = apis[0];
+      if (op.tags && op.tags.length > 0) {
+        const primaryTag = op.tags[0].toLowerCase();
+        const normalizedTag = primaryTag.replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+        const found = apis.find((api) => {
+          const fileName = api.className.toLowerCase();
+          return fileName.includes(normalizedTag) || fileName.includes(primaryTag.replace(/\s+/g, ""));
+        });
+        if (found) {
+          matchedApi = found;
+        }
       }
+      op.className = matchedApi.className;
+      op.sourceFile = matchedApi.sourceFile;
     }
   }
   return {

package/dist/index.js

@@ -3,7 +3,7 @@ import {
   generateDocs,
   renderDocs,
   scanGeneratedFiles
-} from "./chunk-IUOJNB6I.js";
+} from "./chunk-QEPXZXK5.js";
 export {
   extractMetadata,
   generateDocs,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotflash/openapi-semantic-generator",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Semantic mapping automation tool for LLM agents and OpenAPI generated code",
   "type": "module",
   "main": "dist/index.js",
@@ -19,7 +19,8 @@
     "dev": "tsup src/index.ts src/cli.ts --format cjs,esm --watch --shims",
     "test": "vitest run",
     "test:watch": "vitest",
-    "gen:example": "openapi-generator-cli generate -i test/fixtures/petstore.yaml -g typescript-axios -o test/generated/petstore && node dist/cli.js test/fixtures/petstore.yaml -o test/generated/petstore --api-dir api"
+    "gen:example": "openapi-generator-cli generate -i https://petstore3.swagger.io/api/v3/openapi.json -g typescript-axios -o test/generated/petstore && node dist/cli.js https://petstore3.swagger.io/api/v3/openapi.json -o test/generated/petstore",
+    "gen:example:separate": "openapi-generator-cli generate -i https://petstore3.swagger.io/api/v3/openapi.json -g typescript-axios -o test/generated/petstore-separate --additional-properties=withSeparateModelsAndApi=true,apiPackage=apis,modelPackage=models && node dist/cli.js https://petstore3.swagger.io/api/v3/openapi.json -o test/generated/petstore-separate --api-dir apis"
   },
   "keywords": [
     "openapi",