codegen-openapi-ts 0.9.0-alpha.6 → 1.0.1

package/README.md

@@ -1,85 +1,174 @@
-# OpenAPI Typescript Codegen
+# codegen-openapi-ts (alpha)
 
 [![NPM][npm-image]][npm-url]
-[![License][license-image]][license-url]
-[![Coverage][coverage-image]][coverage-url]
-[![Coverage][coverage-image]][coverage-url]
-[![Downloads][downloads-image]][downloads-url]
-[![Build][build-image]][build-url]
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+![Build](https://github.com/devteaa/codegen-openapi-ts/actions/workflows/CI.yml/badge.svg)
 
-> Node.js library that generates Typescript clients based on the OpenAPI specification.
+> Node.js library that generates TypeScript clients from OpenAPI/Swagger specifications.
+
+This project is a fork of [OpenAPI Typescript Codegen](https://github.com/ferdikoomen/openapi-typescript-codegen) by [Ferdi Koomen](https://github.com/ferdikoomen). It adds conversion helpers, a config-file driven CLI, URL/method mapping, model-name mapping, proxy support, and custom append templates.
+
+> ⚠️ **This branch is an alpha release (`v0.9.0-alpha.6`).** The API, config shape, and generated output may still change before `1.0.0`.
 
 ## Why?
-- Frontend ❤️ OpenAPI, but we do not want to use JAVA codegen in our builds
+
+- Frontend ❤️ OpenAPI, but we do not want to use Java codegen in our builds
 - Quick, lightweight, robust and framework-agnostic 🚀
-- Supports generation of TypeScript clients
-- Supports generations of Fetch, Node-Fetch, Axios, Angular and XHR http clients
-- Supports OpenAPI specification v2.0 and v3.0
-- Supports JSON and YAML files for input
-- Supports generation through CLI, Node.js and NPX
-- Supports tsc and @babel/plugin-transform-typescript
-- Supports aborting of requests (cancelable promise pattern)
-- Supports external references using [json-schema-ref-parser](https://github.com/APIDevTools/json-schema-ref-parser/)
+- Supports TypeScript client generation
+- Supports conversion from Swagger 1.x/2.x and other formats to OpenAPI via [`api-spec-converter`](https://github.com/LucyBot-Inc/api-spec-converter)
+- Supports JSON and YAML input files and URLs
+- Supports Fetch, Node-Fetch, Axios, and XHR HTTP clients
+- Supports config-file driven generation with `defineConfig`
+- Supports selecting only specific paths/methods and proxying them
+- Supports external references via [`@apidevtools/json-schema-ref-parser`](https://github.com/APIDevTools/json-schema-ref-parser)
 
 ## Install
 
+```bash
+npm install codegen-openapi-ts --save-dev
 ```
-npm install openapi-typescript-codegen --save-dev
+
+## CLI usage
+
+`codegen-openapi-ts` is driven by a config file.
+
+```bash
+$ codegen-openapi-ts --help
+Usage: codegen-openapi-ts [options]
+
+Options:
+  -V, --version     output the version number
+  --config <value>  Path to config file (default: "codegen.config.js")
+  -h, --help        display help for command
 ```
 
-## Usage
+Create a `codegen.config.js` in your project root:
+
+```javascript
+const { defineConfig } = require('codegen-openapi-ts');
+
+module.exports = defineConfig({
+  // Optional: path to a Handlebars file appended to every generated service
+  appendTemplate: './custom-append.hbs',
+
+  services: [
+    {
+      source: 'https://example.com/openapi.json',
+      from: 'openapi_3', // or 'swagger_1', 'swagger_2', 'api_blueprint', 'io_docs', 'google', 'raml', 'wadl'
+      output: 'src/api-types/example-api',
 
+      // Optional: global path proxy
+      proxyConfig: (path) => path.replace('/api/', '/backend/'),
+
+      // Optional: rename models in the stringified spec before generation
+      modelNameMapping: (json) => json.replace(/some\.long\.name/g, 'ShortName'),
+
+      // Optional: pick and rename specific paths/methods
+      urlMethodMapping: [
+        { originalUrl: '/pokemon-list', method: 'get', methodName: 'GetPokemonList' },
+        { originalUrl: '/pokemon-detail/{id}', method: 'get', methodName: 'GetPokemonDetail', proxyUrl: '/proxy/pokemon-detail/{id}' }
+      ],
+
+      // Optional: only generate paths listed in urlMethodMapping
+      selectedOnly: true
+    }
+  ]
+});
 ```
-$ openapi --help
-
-  Usage: openapi [options]
-
-  Options:
-    -V, --version             output the version number
-    -i, --input <value>       OpenAPI specification, can be a path, url or string content (required)
-    -o, --output <value>      Output directory (required)
-    -c, --client <value>      HTTP client to generate [fetch, xhr, node, axios, angular] (default: "fetch")
-    --name <value>            Custom client class name
-    --useOptions              Use options instead of arguments
-    --useUnionTypes           Use union types instead of enums
-    --exportCore <value>      Write core files to disk (default: true)
-    --exportServices <value>  Write services to disk (default: true)
-    --exportModels <value>    Write models to disk (default: true)
-    --exportSchemas <value>   Write schemas to disk (default: false)
-    --indent <value>          Indentation options [4, 2, tab] (default: "4")
-    --postfixServices         Service name postfix (default: "Service")
-    --postfixModels           Model name postfix
-    --request <value>         Path to custom request file
-    -h, --help                display help for command
-
-  Examples
-    $ openapi --input ./spec.json --output ./generated
-    $ openapi --input ./spec.json --output ./generated --client xhr
+
+Add a script to `package.json`:
+
+```json
+{
+  "scripts": {
+    "codegen": "codegen-openapi-ts"
+  }
+}
 ```
 
-Documentation
-===
+Then run:
 
-The main documentation can be found in the [openapi-typescript-codegen/wiki](https://github.com/ferdikoomen/openapi-typescript-codegen/wiki)
+```bash
+npm run codegen
+```
+
+## Programmatic API
+
+```javascript
+const { generate, convertAndGenerate } = require('codegen-openapi-ts');
+
+// Generate directly from an OpenAPI spec
+await generate({
+  input: './spec.json',
+  output: './generated',
+  httpClient: 'fetch', // 'fetch' | 'xhr' | 'node' | 'axios'
+  clientName: 'MyClient',
+  useUnionTypes: true,
+  exportCore: true,
+  exportServices: true,
+  exportModels: true,
+  exportSchemas: false,
+  indent: '4', // '4' | '2' | 'tab'
+  postfixServices: 'Service',
+  postfixModels: ''
+});
+
+// Convert from another spec format and generate with mappings
+await convertAndGenerate(
+  { from: 'swagger_2', source: 'https://example.com/swagger.json' },
+  { input: './api-schema.json', output: './generated', useUnionTypes: true },
+  [
+    { originalUrl: '/users', method: 'get', methodName: 'GetUsers' }
+  ],
+  true,                         // selectedOnly
+  (json) => json.replace(/OldName/g, 'NewName'), // modelNameMapping
+  '',                           // appendTemplate
+  (path) => path.replace('/v1/', '/v2/') // proxyConfig
+);
+```
 
-Sponsors
-===
+## Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `input` | `string \| object` | — | OpenAPI spec path, URL, or parsed object |
+| `output` | `string` | — | Output directory |
+| `httpClient` | `HttpClient` | `'fetch'` | `'fetch'`, `'xhr'`, `'node'`, `'axios'` |
+| `clientName` | `string` | — | Custom client class name |
+| `useOptions` | `boolean` | `false` | Use options argument for service methods |
+| `useUnionTypes` | `boolean` | `false` | Use union types instead of enums |
+| `exportCore` | `boolean` | `true` | Write `core/` files |
+| `exportServices` | `boolean` | `true` | Write `services/` files |
+| `exportModels` | `boolean` | `true` | Write `models/` files |
+| `exportSchemas` | `boolean` | `false` | Write `schemas/` files |
+| `indent` | `Indent \| '4' \| '2' \| 'tab'` | `'4'` | Indentation style |
+| `postfixServices` | `string` | `'Service'` | Postfix for service names |
+| `postfixModels` | `string` | `''` | Postfix for model names |
+| `request` | `string` | — | Path to a custom request file |
+| `write` | `boolean` | `true` | Write files to disk |
+| `selectedOnly` | `boolean` | `false` | Only generate selected paths (V3) |
+| `appendTemplate` | `string` | — | Path to a Handlebars template appended to services |
+
+## Output folder
+
+The current CLI and `generate()` entry point create:
+
+```text
+output/
+├── models/          # API schema models
+├── services/        # API service classes
+└── index.ts         # barrel exports
+```
 
-If you or your company use the OpenAPI Typescript Codegen, please consider supporting me. By sponsoring I can free up time to give this project some love! Details can be found here: https://github.com/sponsors/ferdikoomen
+The lower-level writer API can also produce `core/` (runtime request helpers, `OpenAPI` config, `CancelablePromise`, etc.) and `schemas/` folders, but these are not generated by the default entry points in this alpha release.
 
-If you're from an enterprise looking for a fully managed SDK generation, please consider our sponsor:
+## Alpha caveats
 
-<a href="https://speakeasyapi.dev/?utm_source=ferdi+repo&utm_medium=github+sponsorship">
-    <img alt="speakeasy" src="https://storage.googleapis.com/speakeasy-design-assets/ferdi-sponsorship.png" width="640"/>
-</a>
+- `convertAndGenerate()` writes a temporary `api-schema.json` to your project root and also stores a copy inside `node_modules/@apidevtools/json-schema-ref-parser/dist/` for `$ref` resolution.
+- The CLI hardcodes `useOptions: true` and `useUnionTypes: true` for config-file generation.
+- `useOptions`, `exportCore`, and `exportSchemas` are accepted by the programmatic API but currently forced to `false` internally. Use the lower-level writer API if you need direct control over these flags.
 
-[npm-url]: https://npmjs.org/package/openapi-typescript-codegen
-[npm-image]: https://img.shields.io/npm/v/openapi-typescript-codegen.svg
-[license-url]: LICENSE
-[license-image]: http://img.shields.io/npm/l/openapi-typescript-codegen.svg
-[coverage-url]: https://codecov.io/gh/ferdikoomen/openapi-typescript-codegen
-[coverage-image]: https://img.shields.io/codecov/c/github/ferdikoomen/openapi-typescript-codegen.svg
-[downloads-url]: http://npm-stat.com/charts.html?package=openapi-typescript-codegen
-[downloads-image]: http://img.shields.io/npm/dm/openapi-typescript-codegen.svg
-[build-url]: https://circleci.com/gh/ferdikoomen/openapi-typescript-codegen/tree/master
-[build-image]: https://circleci.com/gh/ferdikoomen/openapi-typescript-codegen/tree/master.svg?style=svg
+[npm-url]: https://npmjs.org/package/codegen-openapi-ts
+[npm-image]: https://img.shields.io/npm/v/codegen-openapi-ts.svg
+[build-url]: https://github.com/devteaa/codegen-openapi-ts/actions/workflows/CI.yml
+[build-image]: https://github.com/devteaa/codegen-openapi-ts/actions/workflows/CI.yml/badge.svg

package/bin/cli.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+
+import { program } from 'commander';
+import { createRequire } from 'module';
+
+import { generate } from '../dist/index.js';
+
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+
+const params = program
+    .name('openapi')
+    .usage('[options]')
+    .version(pkg.version)
+    .requiredOption('-i, --input <value>', 'OpenAPI specification, can be a path, url or string content (required)')
+    .requiredOption('-o, --output <value>', 'Output directory (required)')
+    .option('-c, --client <value>', 'HTTP client to generate [fetch, xhr, node, axios]', 'fetch')
+    .option('--name <value>', 'Custom client class name')
+    .option('--useOptions', 'Use options instead of arguments')
+    .option('--useUnionTypes', 'Use union types instead of enums')
+    .option('--exportCore <value>', 'Write core files to disk', true)
+    .option('--exportServices <value>', 'Write services to disk', true)
+    .option('--exportModels <value>', 'Write models to disk', true)
+    .option('--exportSchemas <value>', 'Write schemas to disk', false)
+    .option('--indent <value>', 'Indentation options [4, 2, tabs]', '4')
+    .option('--postfixServices <value>', 'Service name postfix', 'Service')
+    .option('--postfixModels <value>', 'Model name postfix')
+    .option('--request <value>', 'Path to custom request file')
+    .parse(process.argv)
+    .opts();
+
+generate({
+    input: params.input,
+    output: params.output,
+    httpClient: params.client,
+    clientName: params.name,
+    useOptions: params.useOptions,
+    useUnionTypes: params.useUnionTypes,
+    exportCore: JSON.parse(params.exportCore) === true,
+    exportServices: JSON.parse(params.exportServices) === true,
+    exportModels: JSON.parse(params.exportModels) === true,
+    exportSchemas: JSON.parse(params.exportSchemas) === true,
+    indent: params.indent,
+    postfixServices: params.postfixServices,
+    postfixModels: params.postfixModels,
+    request: params.request,
+})
+    .then(() => {
+        process.exit(0);
+    })
+    .catch(error => {
+        console.error(error);
+        process.exit(1);
+    });

package/bin/index.js

@@ -1,14 +1,16 @@
 #!/usr/bin/env node
 
-'use strict';
+import { program } from 'commander';
+import { createRequire } from 'module';
+import path from 'path';
+import { pathToFileURL } from 'url';
 
-const path = require('path');
-const { program } = require('commander');
-const esmConfig = require('esm-config');
+import { convertAndGenerate } from '../dist/index.js';
+
+const require = createRequire(import.meta.url);
 const pkg = require('../package.json');
-const OpenAPI = require(path.resolve(__dirname, '../dist/index.js'));
 
-const appRoot = process.cwd().split('/node_modules')[0]
+const appRoot = process.cwd().split('/node_modules')[0];
 
 const params = program
     .name('codegen-openapi-ts')
@@ -18,34 +20,41 @@ const params = program
     .parse(process.argv)
     .opts();
 
-async function generateOnConfig () {
-  try {
-    const configFile = await esmConfig(path.join(appRoot, params.config))
-
-    for (const configService of configFile.services) {
-      console.log('Generating ' + configService.source)
-
-      await OpenAPI.convertAndGenerate(
-        {
-          from: configService.from,
-          source: configService.source
-        },
-        {
-          input: 'api-schema.json',
-          output: configService.output || 'output',
-          useOptions: true,
-          useUnionTypes: true,
-        },
-        configService.urlMethodMapping || [],
-        configService.selectedOnly || false,
-        configService.modelNameMapping,
-        configFile.appendTemplate,
-        configService.proxyConfig
-      )
+async function loadConfig(configPath) {
+    const absolutePath = path.resolve(appRoot, configPath);
+    const configUrl = pathToFileURL(absolutePath).href;
+    const module = await import(configUrl);
+    return module.default ?? module;
+}
+
+async function generateOnConfig() {
+    try {
+        const configFile = await loadConfig(params.config);
+
+        for (const configService of configFile.services) {
+            console.log('Generating ' + configService.source);
+
+            await convertAndGenerate(
+                {
+                    from: configService.from,
+                    source: configService.source,
+                },
+                {
+                    input: 'api-schema.json',
+                    output: configService.output || 'output',
+                    useOptions: true,
+                    useUnionTypes: true,
+                },
+                configService.urlMethodMapping || [],
+                configService.selectedOnly || false,
+                configService.modelNameMapping,
+                configFile.appendTemplate,
+                configService.proxyConfig
+            );
+        }
+    } catch (err) {
+        console.log(err);
     }
-  } catch (err) {
-    console.log(err)
-  }
 }
 
-generateOnConfig()
+generateOnConfig();

package/dist/index.d.ts

@@ -0,0 +1,172 @@
+declare enum HttpClient {
+    FETCH = "fetch",
+    XHR = "xhr",
+    NODE = "node",
+    AXIOS = "axios"
+}
+
+declare enum Indent {
+    SPACE_4 = "4",
+    SPACE_2 = "2",
+    TAB = "tab"
+}
+
+type Options = {
+    input: string | Record<string, any>;
+    output: string;
+    httpClient?: HttpClient;
+    clientName?: string;
+    useOptions?: boolean;
+    useUnionTypes?: boolean;
+    exportCore?: boolean;
+    exportServices?: boolean;
+    exportModels?: boolean;
+    exportSchemas?: boolean;
+    indent?: Indent;
+    postfixServices?: string;
+    postfixModels?: string;
+    request?: string;
+    write?: boolean;
+    selectedOnly?: boolean;
+    appendTemplate?: ReturnType<typeof defineConfig>['appendTemplate'];
+};
+/**
+ * Generate the OpenAPI client. This method will read the OpenAPI specification and based on the
+ * given language it will generate the client, including the typed models, validation schemas,
+ * service layer, etc.
+ * @param input The relative location of the OpenAPI spec
+ * @param output The relative location of the output directory
+ * @param httpClient The selected httpClient (fetch, xhr, node or axios)
+ * @param clientName Custom client class name
+ * @param useOptions Use options or arguments functions
+ * @param useUnionTypes Use union types instead of enums
+ * @param exportCore Generate core client classes
+ * @param exportServices Generate services
+ * @param exportModels Generate models
+ * @param exportSchemas Generate schemas
+ * @param indent Indentation options (4, 2 or tab)
+ * @param postfixServices Service name postfix
+ * @param postfixModels Model name postfix
+ * @param request Path to custom request file
+ * @param write Write the files to disk (true or false)
+ */
+declare const generate: ({ input, output, httpClient, clientName, useOptions, useUnionTypes, exportCore, exportServices, exportModels, exportSchemas, indent, postfixServices, postfixModels, request, write, selectedOnly, appendTemplate, }: Options) => Promise<void>;
+declare const _default: {
+    HttpClient: typeof HttpClient;
+    generate: ({ input, output, httpClient, clientName, useOptions, useUnionTypes, exportCore, exportServices, exportModels, exportSchemas, indent, postfixServices, postfixModels, request, write, selectedOnly, appendTemplate, }: Options) => Promise<void>;
+};
+
+/**
+ * Generate the OpenAPI client with options to convert swagger to openapi etc.
+ * @param converterInput.from The schema specification for the response (swagger_1, swagger_2, openapi_3)
+ * @param converterInput.to The schema specification for the output (openapi_3)
+ * @param converterInput.source The relative location of the OpenAPI spec
+ * @param options.httpClient The selected httpClient (fetch, xhr, node or axios)
+ * @param options.useUnionTypes Use union types instead of enums
+ * @param options.exportCore: Generate core client classes
+ * @param options.exportServices: Generate services
+ * @param options.exportModels: Generate models
+ * @param options.exportSchemas: Generate schemas
+ * @param options.postfix: Service name postfix
+ * @param options.request: Path to custom request file
+ * @param options.write Write the files to disk (true or false)
+ */
+declare function convertAndGenerate({ from, source }: {
+    from: string;
+    source: string;
+}, { input, output, useOptions, useUnionTypes }: Options, urlMethodMapping?: ServiceConfigWithMappings['urlMethodMapping'], selectedOnly?: ServiceConfigWithMappings['selectedOnly'], modelNameMapping?: BaseServiceConfig['modelNameMapping'], appendTemplate?: ReturnType<typeof defineConfig>['appendTemplate'], proxyConfig?: BaseServiceConfig['proxyConfig']): Promise<void>;
+type BaseServiceConfig = {
+    /**
+     * API Docs request url for the json response
+     */
+    source: string;
+    /**
+     * Specify the API specs response format version
+     */
+    from: 'swagger_1' | 'swagger_2' | 'openapi_3' | 'api_blueprint' | 'io_docs' | 'google' | 'raml' | 'wadl';
+    /**
+     * Specify the folder for the codegen output
+     */
+    output: string;
+    /**
+     * Create a function for proxying the request
+     * @example
+     * {
+     *  // ... other config
+     *  proxyConfig: (path) => {
+     *    return path.replace('/api/', '/be/')
+     *  }
+     * }
+     * @param {string} path
+     */
+    proxyConfig?: (path: string) => string;
+    /**
+     * Can be used to replace long model names specified on the schema.
+     * Please use the api-schema.json generated on root project folder
+     * to debug the desired results. Also note that the original schema name
+     * with dot (.) will be generated as underscore (_). Example:
+     * some.long.name will be generated as some_long_name,
+     * if this modelNameMapping supplied
+     * @example
+     * {
+     *  // ... other config
+     *  modelNameMapping: (json) => {
+     *    // remember to use global flag to all regexp used here
+     *    return config.replace(new RegExp('some.long.name', g), 'shortname')
+     *  }
+     * }
+     *
+     * @param {string} json - stringified json schema
+     */
+    modelNameMapping?: (json: string) => string;
+};
+type ServiceConfigDefault = BaseServiceConfig & {
+    urlMethodMapping: undefined;
+    selectedOnly: undefined;
+};
+declare type ServiceConfigWithMappings = BaseServiceConfig & {
+    /**
+     * Custom spec paths mapping. You can configure to rename the method name
+     * or customise the proxyUrl for the specific API
+     *
+     * @example
+     * {
+     *  // ... other config
+     *  urlMethodMapping: [
+     *    { originalUrl: '/pokemon-list', method: 'get', methodName: 'GetPokemonList' },
+     *    { originalUrl: '/pokemon-detail/{id}', method: 'get', methodName: 'GetPokemonList', proxyUrl: '/proxy/pokemon-detail/{id}' }
+     *  ]
+     * }
+     *
+     */
+    urlMethodMapping: {
+        originalUrl: string;
+        method: 'get' | 'post' | 'put' | 'delete';
+        methodName: string;
+        proxyUrl?: string;
+    }[];
+    /**
+     * Flag to only generate listed specs based on urlMethodMapping.
+     * The codegen will still generate all the models listed on the api specs
+     */
+    selectedOnly: boolean;
+};
+/**
+ * Type helper to make it easier to use codegen.config.js
+ */
+declare function defineConfig(config: {
+    /**
+     * Custom api templates append on top of service files
+     */
+    appendTemplate?: string;
+    /**
+     * List config for every services
+     */
+    services: (ServiceConfigDefault | ServiceConfigWithMappings)[];
+}): {
+    appendTemplate?: string | undefined;
+    services: (ServiceConfigDefault | ServiceConfigWithMappings)[];
+};
+
+export { HttpClient, Indent, convertAndGenerate, _default as default, defineConfig, generate };
+export type { BaseServiceConfig, Options, ServiceConfigDefault, ServiceConfigWithMappings };