@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

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

---

Quick Start

1. Create a config file at your project root:

api.generator.config.js:
`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):
`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):
`env
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:
`json
"scripts": {
"generate": "node node_modules/@mintapp/api-generator"
}
`

5. Build and generate:
`bash
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:
`js
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:
`env
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