openapi-sync 2.1.9 → 2.1.11

package/README.md

@@ -35,7 +35,11 @@
 ### 🔧 **Highly Configurable**
 
 - Customizable naming conventions for types and endpoints
-- Flexible output directory structure
+- Exclude/include endpoints by exact path or regex patterns
+- Tag-based filtering, method-specific filtering, and pattern matching
+- Folder splitting configuration for organized code generation
+- OperationId-based naming for better type and endpoint names
+- Flexible output directory structure with custom folder organization
 - URL transformation and text replacement rules
 - Configurable documentation generation
 - Support for multiple API specifications
@@ -151,6 +155,18 @@ const config: IConfig = {
   },
   server: "https://api.example.com", // Override server URL
 
+  // NEW: Folder splitting configuration
+  folderSplit: {
+    byTags: true, // Create folders based on endpoint tags
+    customFolder: ({ method, path, tags, operationId }) => {
+      // Custom logic to determine folder structure
+      if (tags?.includes("admin")) return "admin";
+      if (tags?.includes("public")) return "public";
+      if (path.startsWith("/api/v1/")) return "v1";
+      return null; // Use default folder structure
+    },
+  },
+
   // Type generation configuration
   types: {
     name: {
@@ -201,6 +217,34 @@ const config: IConfig = {
       disable: false,
       showCurl: true, // Include cURL examples in documentation
     },
+    exclude: {
+      // Exclude endpoints by tags
+      tags: ["deprecated", "internal"],
+      // Exclude individual endpoints by path and method
+      endpoints: [
+        // Exact path match
+        { path: "/admin/users", method: "DELETE" },
+        // Regex pattern match
+        { regex: "^/internal/.*", method: "GET" },
+        { regex: ".*/debug$", method: "GET" },
+        // Don't specify method to exclude all methods
+        { path: "/debug/logs" },
+      ],
+    },
+    include: {
+      // Include endpoints by tags
+      tags: ["public"],
+      // Include individual endpoints by path and method
+      endpoints: [
+        // Exact path match
+        { path: "/public/users", method: "GET" },
+        // Regex pattern match
+        { regex: "^/public/.*", method: "GET" },
+        { regex: ".*/logs$", method: "GET" },
+        // Don't specify method to include all methods
+        { path: "/public/logs" },
+      ],
+    },
   },
 };
 
@@ -217,27 +261,81 @@ export default config;
 | `folder`          | `string`                 | Output directory for generated files          | `""`     |
 | `api`             | `Record<string, string>` | Map of API names to OpenAPI spec URLs         | Required |
 | `server`          | `number \| string`       | Server index or custom server URL             | `0`      |
+| `folderSplit`     | `IConfigFolderSplit`     | Configuration for folder splitting            | -        |
 
 #### Type Configuration (`types`)
 
-| Property      | Type       | Description                        |
-| ------------- | ---------- | ---------------------------------- |
-| `name.prefix` | `string`   | Prefix for generated type names    |
-| `name.format` | `function` | Custom naming function for types   |
-| `doc.disable` | `boolean`  | Disable JSDoc generation for types |
+| Property              | Type       | Description                                             |
+| --------------------- | ---------- | ------------------------------------------------------- |
+| `name.prefix`         | `string`   | Prefix for generated type names                         |
+| `name.useOperationId` | `boolean`  | Use OpenAPI operationId for type naming when available  |
+| `name.format`         | `function` | Custom naming function with source context and metadata |
+| `doc.disable`         | `boolean`  | Disable JSDoc generation for types                      |
+
+**OperationId-based Type Naming:**
+
+When `useOperationId` is set to `true`, the system will use the OpenAPI `operationId` for type naming:
+
+- **Query Types**: `{operationId}Query` (e.g., `getUserByIdQuery`)
+- **DTO Types**: `{operationId}DTO` (e.g., `createUserDTO`)
+- **Response Types**: `{operationId}{code}Response` (e.g., `getUserById200Response`)
+
+If `operationId` is not available, the system falls back to the default path-based naming convention.
 
 #### Endpoint Configuration (`endpoints`)
 
-| Property              | Type                   | Description                            |
-| --------------------- | ---------------------- | -------------------------------------- |
-| `value.replaceWords`  | `IConfigReplaceWord[]` | URL transformation rules               |
-| `value.includeServer` | `boolean`              | Include server URL in endpoints        |
-| `value.type`          | `"string" \| "object"` | Output format for endpoints            |
-| `name.prefix`         | `string`               | Prefix for endpoint names              |
-| `name.useOperationId` | `boolean`              | Use OpenAPI operationId for naming     |
-| `name.format`         | `function`             | Custom naming function for endpoints   |
-| `doc.disable`         | `boolean`              | Disable JSDoc generation for endpoints |
-| `doc.showCurl`        | `boolean`              | Include cURL examples in documentation |
+| Property              | Type                                                      | Description                                               |
+| --------------------- | --------------------------------------------------------- | --------------------------------------------------------- |
+| `value.replaceWords`  | `IConfigReplaceWord[]`                                    | URL transformation rules                                  |
+| `value.includeServer` | `boolean`                                                 | Include server URL in endpoints                           |
+| `value.type`          | `"string" \| "object"`                                    | Output format for endpoints                               |
+| `name.prefix`         | `string`                                                  | Prefix for endpoint names                                 |
+| `name.useOperationId` | `boolean`                                                 | Use OpenAPI operationId for naming                        |
+| `name.format`         | `function`                                                | Custom naming function for endpoints                      |
+| `doc.disable`         | `boolean`                                                 | Disable JSDoc generation for endpoints                    |
+| `doc.showCurl`        | `boolean`                                                 | Include cURL examples in documentation                    |
+| `exclude.tags`        | `string[]`                                                | Exclude endpoints by tags                                 |
+| `exclude.endpoints`   | `Array<{path?: string, regex?: string, method?: Method}>` | Exclude specific endpoints by exact path or regex pattern |
+| `include.tags`        | `string[]`                                                | Include endpoints by tags                                 |
+| `include.endpoints`   | `Array<{path?: string, regex?: string, method?: Method}>` | Include specific endpoints by exact path or regex pattern |
+
+#### Folder Splitting Configuration (`folderSplit`)
+
+| Property       | Type       | Description                                   |
+| -------------- | ---------- | --------------------------------------------- |
+| `byTags`       | `boolean`  | Create folders based on endpoint tags         |
+| `customFolder` | `function` | Custom function to determine folder structure |
+
+**Folder Splitting Examples:**
+
+```typescript
+// Split by tags - creates folders like "admin/", "public/", "user/"
+folderSplit: {
+  byTags: true,
+}
+
+// Custom folder logic
+folderSplit: {
+  customFolder: ({ method, path, tags, operationId }) => {
+    // Admin endpoints go to admin folder
+    if (tags?.includes("admin")) return "admin";
+
+    // Public endpoints go to public folder
+    if (tags?.includes("public")) return "public";
+
+    // API versioning
+    if (path.startsWith("/api/v1/")) return "v1";
+    if (path.startsWith("/api/v2/")) return "v2";
+
+    // Method-based organization
+      const method = data.method.toLowerCase();
+    if (method === "get") return "read";
+    if (method === "post" || method === "PUT") return "write";
+
+    return null; // Use default structure
+  },
+}
+```
 
 ## Usage
 
@@ -333,6 +431,8 @@ export default (): IConfig => {
 
 OpenAPI Sync generates a structured output in your specified folder:
 
+### Default Structure
+
 ```
 src/api/
 ├── petstore/
@@ -347,6 +447,37 @@ src/api/
         └── shared.ts
 ```
 
+### Folder Splitting Structure
+
+When `folderSplit.byTags` is enabled or custom folder logic is used:
+
+```
+src/api/
+├── petstore/
+│   ├── admin/                # Endpoints with "admin" tag
+│   │   ├── endpoints.ts
+│   │   └── types/
+│   │       ├── index.ts
+│   │       └── shared.ts
+│   ├── public/               # Endpoints with "public" tag
+│   │   ├── endpoints.ts
+│   │   └── types/
+│   │       ├── index.ts
+│   │       └── shared.ts
+│   └── user/                 # Endpoints with "user" tag
+│       ├── endpoints.ts
+│       └── types/
+│           ├── index.ts
+│           └── shared.ts
+└── auth-api/
+    ├── v1/                   # Custom folder logic
+    │   ├── endpoints.ts
+    │   └── types/
+    └── v2/
+        ├── endpoints.ts
+        └── types/
+```
+
 ### Generated Endpoints
 
 When `endpoints.value.type` is set to `"string"`
@@ -512,11 +643,101 @@ import {
   IOpenApiSpec,
   IOpenApSchemaSpec,
   IConfigReplaceWord,
+  IConfigExclude,
+  IConfigInclude,
+  IConfigDoc,
 } from "openapi-sync/types";
 ```
 
 ## Advanced Examples
 
+### Advanced Folder Splitting Configuration
+
+```typescript
+// openapi.sync.ts
+import { IConfig } from "openapi-sync/types";
+
+const config: IConfig = {
+  refetchInterval: 5000,
+  folder: "./src/api",
+  api: {
+    "main-api": "https://api.example.com/openapi.json",
+  },
+
+  // Advanced folder splitting with multiple strategies
+  folderSplit: {
+    byTags: true, // Enable tag-based splitting
+    customFolder: ({ method, path, tags, operationId }) => {
+      // Priority-based folder assignment
+
+      // 1. Admin endpoints always go to admin folder
+      if (tags?.includes("admin")) return "admin";
+
+      // 2. Public API endpoints
+      if (tags?.includes("public")) return "public";
+
+      // 3. Version-based splitting
+      if (path.startsWith("/api/v1/")) return "v1";
+      if (path.startsWith("/api/v2/")) return "v2";
+
+      // 4. Method-based organization for remaining endpoints
+      if (method === "GET") return "read";
+      if (method === "POST" || method === "PUT" || method === "PATCH")
+        return "write";
+      if (method === "DELETE") return "delete";
+
+      // 5. OperationId-based splitting for specific operations
+      if (operationId?.includes("Auth")) return "auth";
+      if (operationId?.includes("User")) return "user";
+
+      return null; // Use default structure
+    },
+  },
+
+  // Enhanced type naming with operationId support
+  types: {
+    name: {
+      prefix: "I",
+      useOperationId: true, // Use operationId when available
+      format: (source, data, defaultName) => {
+        if (source === "endpoint" && data.operationId) {
+          // Use operationId for better naming
+          switch (data.type) {
+            case "query":
+              return `${data.operationId}Query`;
+            case "dto":
+              return `${data.operationId}DTO`;
+            case "response":
+              return `${data.operationId}${data.code}Response`;
+          }
+        }
+        return defaultName;
+      },
+    },
+  },
+
+  // Enhanced endpoint configuration
+  endpoints: {
+    name: {
+      useOperationId: true, // Use operationId for endpoint names
+      format: ({ operationId, method, path }, defaultName) => {
+        if (operationId) return operationId;
+        return defaultName;
+      },
+    },
+    exclude: {
+      tags: ["deprecated", "internal"],
+      endpoints: [
+        { regex: "^/internal/.*" },
+        { path: "/debug", method: "GET" },
+      ],
+    },
+  },
+};
+
+export default config;
+```
+
 ### Multi-Environment Configuration
 
 ```typescript
@@ -570,17 +791,33 @@ export default getConfig;
 ### Custom Type Formatting
 
 ```typescript
-// Advanced type name formatting
+// Advanced type name formatting with operationId support
 const config: IConfig = {
   // ... other config
   types: {
     name: {
       prefix: "",
+      useOperationId: true, // Use operationId when available
       format: (source, data, defaultName) => {
         if (source === "shared") {
           // Shared types: UserProfile, OrderStatus, etc.
           return `${data.name}`;
         } else if (source === "endpoint") {
+          // Use operationId if available and configured
+          if (data.operationId) {
+            switch (data.type) {
+              case "query":
+                return `${data.operationId}Query`;
+              case "dto":
+                return `${data.operationId}DTO`;
+              case "response":
+                return `${data.operationId}${data.code}Response`;
+              default:
+                return defaultName;
+            }
+          }
+
+          // Fallback to path-based naming
           const method = data.method?.toUpperCase();
           const cleanPath = data.path
             ?.replace(/[{}\/]/g, "_")
@@ -604,6 +841,72 @@ const config: IConfig = {
 };
 ```
 
+### Endpoint Filtering and Selection
+
+```typescript
+// Advanced endpoint filtering configuration
+const config: IConfig = {
+  // ... other config
+  endpoints: {
+    // ... other endpoint config
+    exclude: {
+      // Exclude endpoints by tags
+      tags: ["deprecated", "internal", "admin"],
+      // Exclude specific endpoints by exact path or regex pattern
+      endpoints: [
+        // Exact path matches
+        { path: "/admin/users", method: "DELETE" },
+        { path: "/admin/settings", method: "PUT" },
+        // Regex pattern matches
+        { regex: "^/internal/.*", method: "GET" },
+        { regex: ".*/debug$", method: "POST" },
+        // Exclude all methods for a specific path
+        { path: "/debug/logs" },
+      ],
+    },
+    include: {
+      // Include only public endpoints
+      tags: ["public", "user"],
+      // Include specific endpoints by exact path or regex pattern
+      endpoints: [
+        // Exact path matches
+        { path: "/public/users", method: "GET" },
+        { path: "/public/profile", method: "PUT" },
+        // Regex pattern matches
+        { regex: "^/public/.*", method: "GET" },
+        { regex: ".*/health$", method: "GET" },
+      ],
+    },
+  },
+};
+```
+
+### Path vs Regex Filtering
+
+```typescript
+// Demonstrating the difference between path and regex filtering
+const config: IConfig = {
+  // ... other config
+  endpoints: {
+    exclude: {
+      endpoints: [
+        // Exact path match - only excludes exactly "/api/users"
+        { path: "/api/users", method: "GET" },
+
+        // Regex match - excludes all paths starting with "/api/users"
+        { regex: "^/api/users.*", method: "GET" },
+
+        // Regex match - excludes all paths ending with "/debug"
+        { regex: ".*/debug$", method: "GET" },
+
+        // Regex match - excludes paths with specific pattern
+        { regex: "^/internal/.*/admin$", method: "POST" },
+      ],
+    },
+  },
+};
+```
+
 ### URL Transformation Rules
 
 ```typescript
@@ -859,6 +1162,34 @@ The tool maintains state in `db.json` to track changes:
 
 ---
 
+## Changelog
+
+### v2.1.11 (Latest)
+
+- **NEW**: Folder splitting configuration for organized code generation
+  - `folderSplit.byTags` - Create folders based on endpoint tags
+  - `folderSplit.customFolder` - Custom function for folder structure logic
+- Enhanced folder organization with priority-based assignment
+- Improved code organization for large APIs
+
+### v2.1.10
+
+- OperationId-based naming for types and endpoints
+  - `types.name.useOperationId` - Use OpenAPI operationId for type naming
+  - `endpoints.name.useOperationId` - Use operationId for endpoint naming
+- Enhanced endpoint filtering capabilities
+  - Improved tag-based filtering
+  - Better regex pattern matching
+  - More flexible include/exclude rules
+- Enhanced JSONStringify function with array serialization support
+- Improved endpoint tags support in generated documentation
+
+### Previous Versions
+
+- v2.1.9: Enhanced JSONStringify function improvements
+- v2.1.8: File extension corrections and path handling
+- v2.1.7: Endpoint tags support in API documentation
+
 ## License
 
 This project is licensed under the ISC License - see the [LICENSE](LICENSE) file for details.