@paulpugovkin/api-docs-axios-ts-generator 1.0.5

package/README.md

@@ -0,0 +1,310 @@
+# API Docs Axios TS Generator
+
+Generate TypeScript interfaces and axios classes from OpenAPI (Swagger) specifications.
+
+## Features
+
+- 🚀 Generate TypeScript interfaces from OpenAPI schemas
+- 📦 Generate axios classes with API methods
+- 🔧 Flexible configuration via TypeScript file
+- 🏷️ Tag filtering (include/exclude)
+- 📁 Generation modes: single class or multiple by tags
+- ⚙️ Automatic axios configuration generation
+- 🎯 Support for spreading user axios configurations
+- 📝 JSDoc comments for methods
+- 🔄 Backward compatibility with CLI arguments
+
+## Installation
+
+```bash
+npm install -g @paulpugovkin/api-docs-axios-ts-generator
+```
+
+## Usage
+
+### 1. Install as project dependency
+
+```bash
+npm install --save-dev @paulpugovkin/api-docs-axios-ts-generator
+```
+
+Add script to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "generate-services": "npx @paulpugovkin/api-docs-axios-ts-generator --config api-docs-generator.config.js"
+  }
+}
+```
+
+Now you can run generation:
+
+```bash
+npm run generate-services
+```
+
+
+### 2. Use as global tool
+
+```bash
+# Install as global tool
+npm install -g @paulpugovkin/api-docs-axios-ts-generator
+
+# Run generation
+api-docs-generator --config api-docs-generator.config.js
+
+# Or via npx
+npx @paulpugovkin/api-docs-axios-ts-generator --config api-docs-generator.config.js
+```
+
+### 3. Create configuration file
+
+A default configuration file `api-docs-generator.config.js` is automatically created in your project root during installation. You can modify this file to suit your needs.
+
+If you need to create it manually, create `api-docs-generator.config.js` file in the root of your project:
+
+```javascript
+module.exports = {
+  // URL to fetch OpenAPI specification from
+  apiDocsUrl: 'https://api.example.com/v3/api-docs.json',
+
+  // Output directory for generated files
+  outputDir: './src/api',
+
+  // Tag filtering options
+  tags: {
+    include: ['api_tag_users', 'api_tag_products'],
+  },
+
+  // Grouping mode for API methods
+  groupBy: 'tag',
+
+  // Class generation mode
+  classMode: 'multiple',
+
+  // Generation options
+  options: {
+    generateAxiosConfig: true,
+    allowAxiosConfigSpread: true,
+  },
+
+  // Axios configuration settings
+  axios: {
+    baseURL: 'https://api.example.com',
+    timeout: 30000,
+  },
+};
+```
+
+### 4. Use generated API
+
+```typescript
+import { UsersApi, ProductsApi } from './src/api';
+
+// Use API
+const usersApi = new UsersApi();
+const productsApi = new ProductsApi();
+
+// Get user
+const user = await usersApi.getUserById(123);
+
+// With custom axios configuration
+const user = await usersApi.getUserById(123, {
+  headers: {
+    'X-Custom-Header': 'value',
+  },
+  timeout: 5000,
+});
+```
+
+## Configuration
+
+### Main parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|--------------|------------|
+| `apiDocsUrl` | `string` | No* | URL to fetch OpenAPI specification |
+| `apiDocsPath` | `string` | No* | Local path to OpenAPI specification file |
+| `outputDir` | `string` | Yes | Output directory for generated files |
+
+*One of `apiDocsUrl` or `apiDocsPath` is required.
+
+### Tag filtering
+
+```typescript
+tags: {
+  include?: string[];    // Tags to include
+  exclude?: string[];    // Tags to exclude
+  prefix?: string;        // Tag prefix (default "api_tag_")
+}
+```
+
+### Grouping modes
+
+```typescript
+groupBy: 'tag' | 'all' | 'path';
+```
+
+- `'tag'` - grouping by tags (multiple classes)
+- `'all'` - all methods in one class
+- `'path'` - grouping by API paths
+
+### Class generation modes
+
+```typescript
+classMode: 'single' | 'multiple';
+```
+
+- `'single'` - one class for all methods
+- `'multiple'` - multiple classes by grouping
+
+### Naming options
+
+```typescript
+naming: {
+  className?: (tag: string) => string;
+  interfaceName?: (name: string) => string;
+  methodName?: (operationId: string) => string;
+}
+```
+
+### Import options
+
+```typescript
+imports: {
+  axiosPath?: string;      // Path to import axios (default 'axios')
+  baseUrlPath?: string;   // Path to import BASE_URL
+}
+```
+
+### Generation options
+
+```typescript
+options: {
+  generateJSDoc?: boolean;           // Generate JSDoc (default true)
+  generateIndexFiles?: boolean;      // Generate index files (default true)
+  cleanOutputDir?: boolean;          // Clean output directory (default true)
+  generateAxiosConfig?: boolean;     // Generate axios configuration (default true)
+  allowAxiosConfigSpread?: boolean;  // Allow spreading axios configs (default true)
+}
+```
+
+### Axios settings
+
+```typescript
+axios: {
+  baseURL?: string;
+  timeout?: number;
+  headers?: Record<string, string>;
+  withCredentials?: boolean;
+}
+```
+
+## Spreading user axios configurations
+
+When `allowAxiosConfigSpread: true` is enabled, API methods support passing user configurations:
+
+```typescript
+// Generated method
+async getUserById(id: number, config?: AxiosRequestConfig): Promise<AxiosResponse<User>>
+
+// Usage
+const response = await usersApi.getUserById(123, {
+  headers: {
+    'X-Custom-Header': 'value',
+  },
+  timeout: 5000,
+  params: {
+    fields: 'id,name,email',
+  },
+});
+```
+
+## Generated files structure
+
+```
+outputDir/
+├── config/
+│   └── axios/
+│       └── axios.ts          # Axios configuration with interceptors
+├── interfaces/
+│   ├── User.ts
+│   ├── Product.ts
+│   └── index.ts
+├── classes/
+│   ├── UsersApi.ts
+│   ├── ProductsApi.ts
+│   └── index.ts
+└── index.ts
+```
+
+## CLI options
+
+```
+Usage: api-docs-generator [options]
+
+Options:
+  -V, --version                 output the version number
+  -c, --config <path>           Path to configuration file
+  --api-docs-url <url>         URL to fetch OpenAPI documentation
+  --api-docs-path <path>       Local path to OpenAPI documentation file
+  --output-dir <dir>            Output directory for generated files
+  --clean                        Clean output directory before generation
+  -h, --help                    display help for command
+```
+
+## Configuration examples
+
+### Generate by tags (multiple classes)
+
+```typescript
+{
+  tags: {
+    include: ['api_tag_users', 'api_tag_products'],
+  },
+  groupBy: 'tag',
+  classMode: 'multiple',
+}
+```
+
+### Generate single class
+
+```typescript
+{
+  groupBy: 'all',
+  classMode: 'single',
+}
+```
+
+### Exclude tags
+
+```typescript
+{
+  tags: {
+    exclude: ['api_tag_internal', 'api_tag_admin'],
+  },
+}
+```
+
+### Generate with axios configuration
+
+```typescript
+{
+  options: {
+    generateAxiosConfig: true,
+  },
+  axios: {
+    baseURL: 'https://api.example.com',
+    timeout: 30000,
+    headers: {
+      'Content-Type': 'application/json',
+      'X-API-Key': 'your-api-key',
+    },
+  },
+}
+```
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+/**
+ * CLI entry point for api-docs-axios-ts-generator
+ */
+require('../src/index.js');

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@paulpugovkin/api-docs-axios-ts-generator",
+  "version": "1.0.5",
+  "description": "Generate TypeScript interfaces and axios classes from OpenAPI documentation",
+  "main": "src/index.min.js",
+  "bin": {
+    "api-docs-generator": "./src/index.min.js"
+  },
+  "types": "src/types/index.d.ts",
+  "scripts": {
+    "generate-services": "npx @paulpugovkin/api-docs-axios-ts-generator --config api-docs-generator.config.js",
+    "postinstall": "node src/scripts/createConfigFile.js"
+  },
+  "keywords": [
+    "openapi",
+    "swagger",
+    "typescript",
+    "axios",
+    "generator",
+    "api-client",
+    "code-generation",
+    "api",
+    "rest"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^11.0.0",
+    "node-fetch": "^2.7.0",
+    "axios": "^1.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "files": [
+    "src",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PaulPugovkin/api-docs-axios-ts-generator.git"
+  },
+  "bugs": {
+    "url": "https://github.com/PaulPugovkin/api-docs-axios-ts-generator/issues"
+  },
+  "homepage": "https://github.com/PaulPugovkin/api-docs-axios-ts-generator#readme"
+}

package/src/clean-generated-folder/cleanGeneratedFolder.js

@@ -0,0 +1,21 @@
+const fs = require("fs");
+const path = require("path");
+
+/**
+ * Удаляет содержимое папки и пересоздает её.
+ * @param {string} outputDir - Путь к папке.
+ */
+function cleanGeneratedFolder(outputDir) {
+    if (fs.existsSync(outputDir)) {
+        fs.rmSync(outputDir, {recursive: true}); // Удаляем папку и все вложенные файлы
+        console.log(`Deleted: ${outputDir}`);
+    }
+
+    fs.mkdirSync(outputDir, {recursive: true}); // Создаем основную папку
+    fs.mkdirSync(path.join(outputDir, "interfaces"), {recursive: true});
+    fs.mkdirSync(path.join(outputDir, "classes"), {recursive: true});
+
+    console.log(`Recreated necessary directories.`);
+}
+
+module.exports = {cleanGeneratedFolder};

package/src/collect-genereted-files/collectGeneratedFiles.js

@@ -0,0 +1,33 @@
+const fs = require("fs");
+const path = require("path");
+
+function collectGeneratedFiles(outputDir) {
+    const classFiles = [];
+    const interfaceFiles = [];
+
+    // Рекурсивный обход папок
+    function walkDir(currentPath) {
+        const entries = fs.readdirSync(currentPath, {withFileTypes: true});
+        for (const entry of entries) {
+            const fullPath = path.join(currentPath, entry.name);
+
+            if (entry.isDirectory()) {
+                walkDir(fullPath); // Рекурсивный вызов для папок
+            } else if (
+                entry.isFile() &&
+                entry.name.endsWith(".ts") &&
+                entry.name !== "index.ts"
+            ) {
+                if (fullPath.includes("interfaces")) {
+                    interfaceFiles.push(fullPath);
+                } else {
+                    classFiles.push(fullPath);
+                }
+            }
+        }
+    }
+
+    walkDir(outputDir); // Запуск обхода с указанной папки
+
+    return {classFiles, interfaceFiles};
+}

package/src/config/defaultConfig.ts

@@ -0,0 +1,33 @@
+/**
+ * Конфигурация по умолчанию для генератора
+ */
+import { GeneratorConfig } from '../types/config.types';
+
+export const defaultConfig: Partial<GeneratorConfig> = {
+  outputDir: './generated',
+  interfacesDir: './generated/interfaces',
+  classesDir: './generated/classes',
+  groupBy: 'tag',
+  classMode: 'multiple',
+  tags: {
+    prefix: 'api_tag_',
+  },
+  imports: {
+    axiosPath: 'axios',
+    baseUrlPath: './config/axios/axios',
+  },
+  options: {
+    generateJSDoc: true,
+    generateIndexFiles: true,
+    cleanOutputDir: true,
+    generateAxiosConfig: true,
+    allowAxiosConfigSpread: true,
+  },
+  axios: {
+    baseURL: '',
+    timeout: 30000,
+    headers: {
+      'Content-Type': 'application/json',
+    },
+  },
+};

package/src/config/loadConfig.ts

@@ -0,0 +1,112 @@
+/**
+ * Загрузка конфигурации генератора
+ */
+// @ts-ignore - Node.js types
+import fs from 'fs';
+// @ts-ignore - Node.js types
+import path from 'path';
+import { GeneratorConfig } from '../types/config.types';
+import { defaultConfig } from './defaultConfig';
+import { validateConfig } from './validateConfig';
+
+/**
+ * Загружает конфигурацию из файла
+ * @param configPath - Путь к файлу конфигурации
+ * @returns Объект конфигурации
+ */
+async function loadConfigFile(configPath: string): Promise<Partial<GeneratorConfig>> {
+  const resolvedPath = path.resolve(configPath);
+
+  if (!fs.existsSync(resolvedPath)) {
+    throw new Error(`Configuration file not found: ${resolvedPath}`);
+  }
+
+  // Удаляем кэш для поддержки горячей перезагрузки
+  // @ts-ignore
+  delete require.cache[require.resolve(resolvedPath)];
+
+  try {
+    // @ts-ignore
+    const userConfig = require(resolvedPath);
+    return userConfig.default || userConfig;
+  } catch (error) {
+    throw new Error(`Failed to load configuration from ${resolvedPath}: ${error}`);
+  }
+}
+
+/**
+ * Объединяет конфигурации (пользовательская перекрывает дефолтную)
+ * @param defaults - Конфигурация по умолчанию
+ * @param userConfig - Пользовательская конфигурация
+ * @returns Объединённая конфигурация
+ */
+function mergeConfigs(
+  defaults: Partial<GeneratorConfig>,
+  userConfig: Partial<GeneratorConfig>
+): GeneratorConfig {
+  const merged: any = {
+    ...defaults,
+    ...userConfig,
+  };
+
+  // Глубокое слияние для вложенных объектов
+  if (defaults.tags && userConfig.tags) {
+    merged.tags = { ...defaults.tags, ...userConfig.tags };
+  }
+
+  if (defaults.naming && userConfig.naming) {
+    merged.naming = { ...defaults.naming, ...userConfig.naming };
+  }
+
+  if (defaults.imports && userConfig.imports) {
+    merged.imports = { ...defaults.imports, ...userConfig.imports };
+  }
+
+  if (defaults.options && userConfig.options) {
+    merged.options = { ...defaults.options, ...userConfig.options };
+  }
+
+  if (defaults.axios && userConfig.axios) {
+    merged.axios = { ...defaults.axios, ...userConfig.axios };
+    // Глубокое слияние для headers
+    if (defaults.axios.headers && userConfig.axios.headers) {
+      merged.axios.headers = { ...defaults.axios.headers, ...userConfig.axios.headers };
+    }
+  }
+
+  return merged as GeneratorConfig;
+}
+
+/**
+ * Загружает конфигурацию генератора
+ * @param configPath - Путь к файлу конфигурации (опционально)
+ * @param cliOverrides - Переопределения из CLI аргументов
+ * @returns Полная конфигурация генератора
+ */
+export async function loadConfig(
+  configPath?: string,
+  cliOverrides?: Partial<GeneratorConfig>
+): Promise<GeneratorConfig> {
+  let userConfig: Partial<GeneratorConfig> = {};
+
+  // Загрузка из файла, если указан
+  if (configPath) {
+    console.log(`Loading configuration from: ${configPath}`);
+    userConfig = await loadConfigFile(configPath);
+  } else {
+    console.log('No configuration file specified, using default configuration');
+  }
+
+  // Слияние с конфигурацией по умолчанию
+  let mergedConfig = mergeConfigs(defaultConfig, userConfig);
+
+  // Применение переопределений из CLI
+  if (cliOverrides) {
+    mergedConfig = mergeConfigs(mergedConfig, cliOverrides);
+  }
+
+  // Валидация конфигурации
+  validateConfig(mergedConfig);
+
+  return mergedConfig;
+}

package/src/config/validateConfig.ts

@@ -0,0 +1,58 @@
+/**
+ * Валидация конфигурации генератора
+ */
+import { GeneratorConfig } from '../types/config.types';
+
+export function validateConfig(config: GeneratorConfig): void {
+  // Проверка обязательного поля outputDir
+  if (!config.outputDir) {
+    throw new Error('Configuration error: outputDir is required');
+  }
+
+  // Проверка, что указан либо apiDocsUrl, либо apiDocsPath
+  if (!config.apiDocsUrl && !config.apiDocsPath) {
+    throw new Error('Configuration error: either apiDocsUrl or apiDocsPath must be specified');
+  }
+
+  // Проверка groupBy
+  if (config.groupBy && !['tag', 'all', 'path'].includes(config.groupBy)) {
+    throw new Error(`Configuration error: invalid groupBy value "${config.groupBy}". Must be one of: tag, all, path`);
+  }
+
+  // Проверка classMode
+  if (config.classMode && !['single', 'multiple'].includes(config.classMode)) {
+    throw new Error(`Configuration error: invalid classMode value "${config.classMode}". Must be one of: single, multiple`);
+  }
+
+  // Проверка фильтрации по тегам
+  if (config.tags) {
+    if (config.tags.include && config.tags.exclude) {
+      console.warn('Warning: Both include and exclude tags are specified. Include will take precedence.');
+    }
+
+    if (config.tags.include && config.tags.include.length === 0) {
+      console.warn('Warning: tags.include is empty. No tags will be filtered.');
+    }
+  }
+
+  // Проверка совместимости groupBy и classMode
+  if (config.groupBy === 'all' && config.classMode === 'multiple') {
+    console.warn('Warning: groupBy="all" with classMode="multiple" will generate only one class. Consider using classMode="single".');
+  }
+
+  // Проверка настроек axios
+  if (config.axios) {
+    if (config.axios.timeout !== undefined && config.axios.timeout < 0) {
+      throw new Error('Configuration error: axios.timeout must be a positive number');
+    }
+  }
+
+  // Проверка опций генерации
+  if (config.options) {
+    if (config.options.generateAxiosConfig && !config.axios) {
+      console.warn('Warning: generateAxiosConfig is true but no axios config provided. Using default values.');
+    }
+  }
+
+  console.log('Configuration validated successfully.');
+}

package/src/generate-class/generateClass.js

@@ -0,0 +1,35 @@
+/**
+ * Генерация классов TypeScript
+ * @param {string} name - Название класса
+ * @param {string[]} methods - Список методов класса
+ * @param {Set<string>} usedInterfaces - Набор используемых интерфейсов
+ * @param {Object} config - Конфигурация генератора
+ * @returns {string} - Сгенерированный код класса TypeScript
+ */
+function generateClass(name, methods, usedInterfaces, config) {
+    const axiosResponseImport =
+        'import { AxiosResponse, AxiosRequestConfig } from "axios";\n';
+
+    // Определяем пути импорта из конфигурации
+    const axiosPath = config?.imports?.axiosPath || 'axios';
+    const baseUrlPath = config?.imports?.baseUrlPath || './config/axios/axios';
+
+    // Импорты интерфейсов
+    let interfaceImport = '';
+    if (usedInterfaces && usedInterfaces.size > 0) {
+        interfaceImport = Array.from(usedInterfaces)
+            .sort()
+            .map((interfaceName) => `import { ${interfaceName} } from '../../';`)
+            .join("\n");
+    }
+
+    // Импорты axios
+    const axiosImport = `\nimport axios from '${axiosPath}'`;
+    const baseApiUrl = `\nimport { BASE_URL } from '${baseUrlPath}'`;
+
+    const imports = `${axiosResponseImport}${interfaceImport}${axiosImport}${baseApiUrl}`;
+    const tsMethods = methods.join("\n");
+    return `${imports}\n\nexport class ${name} {\n${tsMethods}\n}\n`;
+}
+
+module.exports = {generateClass};