api-client-generator

API client generator

Generated files are compatible with Angular 6 (should be compatible with 5 version too).
RxJS imports are targeted for version 6+.

Description

This package generates an Angular TypeScript class from a Swagger v2.0 specification file. The code is generated using Mustache templates.

The generated service class uses new HttpClient module of Angular (introduced in version 4.3).

Motivation

This tool provides an easy and sustainable solution for making the classic REST API feel like you wish it has felt in TypeScript.

It starts by having the same data models at front-end and back-end, then continues with API client interface in form of service build on Angular HTTP client. Everything is typed and described in the way developer don't even need to study the API endpoints.

All you need to set it up is an up to date swagger file and Angular project.

How is this relevant for you?

A lot of developers is struggling with how to properly use the REST API in their apps. In Angular, we have a great opportunity which is HTTP Client supporting types. It is a great experience when you can work on a project where your models and data service are pre-generated and you can focus on state management, UI and business logic.

Compatibility

Angular 6+ (it should also work with 5 and 4.3+)

RxJS 6 (Observable imports)

in case of rxjs <6 please update or rewrite the rxjs imports to match the older version

NOTE: if you want to skip the installation for project, you can use npx but be careful as you'll be using the latest version every time you run the script (We use SEMVER so it is safer to update over the time).

Options

Option

Description

-h/--help

print help and exit

-s/--source

path to the swagger file (YAML or JSON)

-o/--output

path where the generated files should be emitted

-C/--commit

git commit generated changes *

-v/--verbose

supply stack traces with outputted error messages

-t/--splitPathTags

generate services and models only for the specified tags. Use , as the separator for multiple tags

use all to emit all as a service per tag

-m/--skipModule

skip creating the index file with module export

* The author of the commit will be api-client-generator <api-client-generator@flowup.cz>.
If there are any staged changes in your repository, the generator will halt pre-generation with an error to prevent including your changes in the automatic commit.*

How to use generated client

import the APIClientModule in your app.module.ts (main module)

domain and configuration should be passed to module imports using .forRoot method

options and domain are optional

when a domain is not passed, host property form swagger file is used as a default

if host property is not defined window.href with a current port is used instead

@NgModule({

imports:[

/* Default configuration and all of it's properties is optional */

APIClientModule.forRoot({

domain:'https://api.url',// or use value defined in environment `environment.apiUrl`

httpOptions:{

headers:{

myCustomHeader:

'this will appear in every request as one of the headers',

},

params:{someParam:'customParam'},

},

}),

/* ... other imports */

HttpClientModule,// <<= this is very important import

// API client relies on HttpClient module and will throw and provider error if not there

],

/* ... other stuff */

})

exportclassAppModule{}

use APIClient service in your components/services/...

@Component({

selector:'my-component',

templateUrl:`

<div *ngFor="let user of users">

<p>User name: {{user.name}}</p>

</div>

`,

})

exportclassMyComponent{

users:User[]=[];

constructor(privatereadonlyapi:APIClient){

this.api.getUsers().subscribe(users=>(this.users=users));

}

}

Generated structure

if you are interested in how will the generated client with models look like, take a look in an example/ folder

Numeric Enums keys generated as plane number

If some of your numeric enums look like this, the problem might be that in the swagger file you are not describing the keys properly.

export enum MyEnum {
0 = 0,
1 = 1,
2 = 2,
}

Fix
We currently support two options:

formatting description into array of ['1 Foo', '2 Bar']

using 'x-enumNames' custom property that should be in format ['Foo', 'Bar']

Problem reporting and contributions

Please report any problems you have any issues you find so they can be resolved.
If the generator terminates with an error message, please re-run it with the -v flag and post the outputted stack trace.

Feel free to discuss desired improvements or functionality in issues. Afterwards, the pull requests are very welcome.