@mintapp/api-generator

Generate fully-typed API clients (interfaces + axios wrappers) from OpenAPI/Swagger JSON. Designed for TypeScript projects that want type-safe, auto-updated API code.

Features

• Automatic codegen: Generates TypeScript interfaces and axios-based API functions from your OpenAPI/Swagger spec.
• Strong typing: All DTOs, enums, and API methods are fully typed.
• Configurable: Supports per-API config, custom output directory, DTO suffix, nullable fields, locale headers, and more.
• No runtime dependency: Only generates code; your runtime stays clean.

Installation

npm install @mintapp/api-generator --save-dev

Quick Start

1. Create a config file at your project root:

   api.generator.config.js:

   module.exports = () => [
       {
           nameSpace: 'myApi',
           apiUrl: 'https://api.example.com',
           apiUsername: 'user',
           apiPassword: 'pass',
           path: '/swagger/v1',
           swaggerFilePath: 'swagger.json',
           baseDirectory: 'api',
           locale: false,
           dtoSuffix: true,
           allowNullable: false,
       },
   ];

2. Add a minimal axios instance to your output directory (e.g. api/axios.ts):

   import axios, { AxiosRequestConfig } from 'axios';
   const API_URL = process.env.API_URL;
   if (!API_URL) throw new Error('Please provide the API_URL environment variable.');
   const config: AxiosRequestConfig = { baseURL: API_URL };
   const instance = axios.create(config);
   export default instance;

3. Set up your environment variables (if not in config):

   API_URL=https://api.example.com
   API_USERNAME=user
   API_PASSWORD=pass
   # Optional: custom header
   HEADER_KEY=X-API-KEY
   HEADER_VALUE=123456

4. Add a script to your package.json:

   "scripts": {
       "generate": "node node_modules/@mintapp/api-generator"
   }

5. Build and generate:

   npm run build
   npm run generate

6. Use your generated API:

   • Find output in api/generated/ (or your chosen directory):
     • myApiInterfaces.ts (types)
     • myApiApi.ts (axios wrappers)

Configuration

You can use either a config file (api.generator.config.js) or CLI/env fallback. See copilot-instructions.md for all options.

Config file example:

module.exports = () => [
    {
        nameSpace: 'myApi',
        apiUrl: 'https://api.example.com',
        apiUsername: 'user',
        apiPassword: 'pass',
        path: '/swagger/v1',
        swaggerFilePath: 'swagger.json',
        baseDirectory: 'api',
        locale: false,
        localeHeaderKey: 'X-Accept-Language',
        dtoSuffix: true,
        allowNullable: false,
    },
];

.env fallback:

API_URL=https://api.example.com
API_USERNAME=user
API_PASSWORD=pass
GENERATOR_PATH=/swagger/v1

Advanced Usage

• Multiple APIs: Add multiple objects to the config array.
• Locale header: Set locale: true and optionally localeHeaderKey.
• DTO suffix: Set dtoSuffix: false to remove Dto from type names.
• Nullable fields: Set allowNullable: true to use ? for nullable properties.
• Custom headers: Use HEADER_KEY and HEADER_VALUE in .env.

Contributing

Pull requests are welcome! Please see CONTRIBUTING.md if available, or open an issue for questions/ideas.

Support & Feedback

• GitHub Issues
• NPM Package

License

ISC © Gil Bliman / Mintapp