README
OpenAPI Typescript Codegen
This is a fork until this PR is closed: https://github.com/ferdikoomen/openapi-typescript-codegen/pull/377
Node.js library that generates Typescript clients based on the OpenAPI specification.
Why?
- 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 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
Install
npm install openapi-typescript-codegen --save-dev
Usage
$ 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] (default: "fetch")
--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)
Examples
$ openapi --input ./spec.json
$ openapi --input ./spec.json --output ./dist
$ openapi --input ./spec.json --output ./dist --client xhr
Example
package.json
{
"scripts": {
"generate": "openapi --input ./spec.json --output ./dist"
}
}
NPX
npx openapi-typescript-codegen --input ./spec.json --output ./dist
Node.js API
const OpenAPI = require('openapi-typescript-codegen');
OpenAPI.generate({
input: './spec.json',
output: './dist'
});
// Or by providing the content of the spec directly 🚀
OpenAPI.generate({
input: require('./spec.json'),
output: './dist'
});
Features
--useOptions
Argument style vs. Object style There's no named parameter in JavaScript or TypeScript, because of
that, we offer the flag --useOptions
to generate code in two different styles.
Argument-style:
function createUser(name: string, password: string, type?: string, address?: string) {
// ...
}
// Usage
createUser('Jack', '123456', undefined, 'NY US');
Object-style:
function createUser({ name, password, type, address }: {
name: string,
password: string,
type?: string
address?: string
}) {
// ...
}
// Usage
createUser({
name: 'Jack',
password: '123456',
address: 'NY US'
});
--useUnionTypes
Enums vs. Union Types The OpenAPI spec allows you to define enums inside the
data model. By default, we convert these enums definitions to TypeScript enums.
However, these enums are merged inside the namespace of the model, this is unsupported by Babel, see docs.
Because we also want to support projects that use Babel @babel/plugin-transform-typescript,
we offer the flag --useOptions
to generate union types
instead of the traditional enums. The difference can be seen below:
Enums:
// Model
export interface Order {
id?: number;
quantity?: number;
status?: Order.status;
}
export namespace Order {
export enum status {
PLACED = 'placed',
APPROVED = 'approved',
DELIVERED = 'delivered',
}
}
// Usage
const order: Order = {
id: 1,
quantity: 40,
status: Order.status.PLACED
}
Union Types:
// Model
export interface Order {
id?: number;
quantity?: number;
status?: 'placed' | 'approved' | 'delivered';
}
// Usage
const order: Order = {
id: 1,
quantity: 40,
status: 'placed'
}
--exportSchemas
Runtime schemas By default, the OpenAPI generator only exports interfaces for your models. These interfaces will help you during
development, but will not be available in JavaScript during runtime. However, Swagger allows you to define properties
that can be useful during runtime, for instance: maxLength
of a string or a pattern
to match, etc. Let's say
we have the following model:
{
"MyModel": {
"required": [
"key",
"name"
],
"type": "object",
"properties": {
"key": {
"maxLength": 64,
"pattern": "^[a-zA-Z0-9_]*