angular-swagger2
v1.3.0
Published
Generator of types, API and NGRX layer in TypeScript for Angular 12 apps
Downloads
1
Maintainers
Readme
Angular Swagger2
This repository was derived from swagger-angular-generator. The main difference is that it drops support for form services and extends ngrx generation capabilities, introduces eslint and Angular 12 support.
Purpose
Generate minimalistic TypeScript API layer for Angular with full type reflection of backend model.
- Source: swagger scheme
- Destination: Angular-cli based Angular app.
What is generated
Services for back-end / API communication
- connect to your API in no-time
Interfaces
- request and response interfaces are created
NGRX modules for endpoints (optional)
- so that the server responses can be reached in the redux store
- requests can be triggered by dispatching an action
Have a look at the demo-app generated files to get better understanding what is being generated.
Install
npm i angular-swagger2
Options
-h
- show help-s
,--src
- source directory-d
,--dest
- destination directory, default:src/api
--no-store
- do not generate the ngrx modules-u, --swagger-URL-path
- swagger URL path, where the swagger ui documentation can be found; default:/swagger
, i.e. the resulting address would behttp://example/swagger
-o, --omit-version
- disables API version information to be generated in comments for each file
Use
Run generator
- get the swagger scheme (typically at http(s)://[server]/[app-path]/v2/api/api-docs)
- save it to json file in input directory and optionally format it for better diff
- run via
- directly
./node_modules/.bin/angular-swagger2
- as module
angular-swagger2
package,npm run generate
"script": { "generate": "angular-swagger2 -s src/api/scheme.json -d src/api/generated" ... }
- or programatically as a method invocation
import {generate} from 'angular-swagger2'; // or using CommonJS loader const {generate} = require('angular-swagger2'); generate('conf/api/api-docs.json', 'src/api');
- directly
The resulting API layer contains the following structure in the destination directory:
controllers
directory stores services containing all API methods devided by controllersdefs
directory stores all response interfaces and enumsstore
directory has modules, which contain NGRX actions, reducers and effectsmodel.ts
file reexports all of them together for a simple access
When updating your code for new backend version, we recommend you to follow these steps:
git diff
the changes- run
tsc
for immediate problems - adjust the code, solve problems
- commit
Use
In order to consume generated model, follow the steps 1-9 in the following example to use generated API model.
API service usage in component
// 1. import used response interfaces
import {ItemDto, PageDto} from '[relative-path-to-destination-directory]/model';
// 2. import used API service and optionally param interfaces
import {DataService, MethodParams} from '[relative-path-to-destination-directory]/api/DataService';
@Component({
...
// 3. make the service injectable (can be also imported in the module)
providers: [DataService],
})
export class MyComponent implements OnInit {
// 4. declare response object variables based on the generated API interfaces
public items: ItemDto[] = [];
public page: PageDto;
// 5. declare request params based on the generated API interface (all params are passed together in one object)
private params: MethodParams = {
page: 0,
size: 10,
sort: ['name:asc']
};
// 6. inject the API service
constructor(private dataService: DataService) {}
public ngOnInit() {
// 7. the returned observable is fully typed
this.dataService
.get(this.params)
// 8. returned data are fully typed
.subscribe(data => {
// 9. assignments are type-checked
this.items = data.content;
this.page = data.page;
});
}
}
NGRX workflow with generated modules, actions, effects, reducerss
Import the generated module
@NgModule({
imports: [
...,
ExampleModule,
...,
],
})
export class YourModule {}
- the generated module looks like this
@NgModule({
imports: [
NgrxStoreModule.forFeature(selectorName, ExampleReducer),
NgrxEffectsModule.forFeature([ExampleEffects]),
],
providers: [
ExampleService,
],
})
export class ExampleModule {}
Component (created by you)
In the component, send the above created form via sendForm()
method. Notice the way a generated anction is dispatched.
import {Component, OnDestroy} from '@angular/core';
import {Store} from '@ngrx/store';
import {takeUntil} from 'rxjs/operators';
import {Subject} from 'rxjs/Subject';
import {ExampleStart} from '../../generated/store/example/exampleModule/states/actions';
import {AppState} from '../states/exmaple.models';
@Component({
selector: 'example-component',
templateUrl: 'example-component.html',
})
export class ExampleComponent implements OnDestroy {
constructor(
private store: Store<AppState>,
) {}
sendForm() {
this.store.dispatch(new ExampleStart());
}
ngOnDestroy() {
this.ngDestroy.next();
this.ngDestroy.complete();
}
}
Effect (generated)
- the dispatched method is intercepted by an effect which calls the API via the generated API service
- upon success, a
Success
action is dispatched (payload is the server response data) - upon error, an
Error
action is dispatched (payload is the error message sent from the server)
@Injectable()
export class ExampleEffects {
@Effect()
CreateProductCategory = this.storeActions.ofType<ExampleStart>(ExampleActions.START).pipe(
switchMap((action: ExampleStart) => this.exampleService.exampleEndpointMethod(action.payload)
.pipe(
map(result => new ExampleSuccess(result)),
catchError((error: HttpErrorResponse) => of(new ExampleError(error.message))),
),
),
);
constructor(
private storeActions: Actions,
private adminproductService: AdminProductService,
) {}
}
Reducer (generated)
- the reducer catches the
Success
/Error
actions dispatched by the generated effect and stores the payloads to the store
export interface ExampleState {
data: __model.ExampleServerResponseInterface;
loading: boolean;
error: string;
}
export const initialExampleState: ExampleState = {
data: null,
loading: false,
error: null,
};
export const selectorName = 'Example';
export const getExampleSelector = createFeatureSelector<ExampleState>(selectorName);
export function ExampleReducer(
state: ExampleState = initialExampleState,
action: ExampleAction): ExampleState {
switch (action.type) {
case ExampleActions.START: return {...state, loading: true, error: null};
case ExampleActions.SUCCESS: return {...state, data: action.payload, loading: false};
case ExampleActions.ERROR: return {...state, error: action.payload, loading: false};
default: return state;
}
}
Component (again)
- the data can be retrieved by subscribing to the store
ngOnInit() {
this.exampleState = this.store.pipe(
takeUntil(this.ngDestroy),
select(getExampleSelector));
// OR
this.data = this.store.select(s => ExampleState.data)
this.loading = this.store.select(s => ExampleState.loading)
this.error = this.store.select(s => ExampleState.error)
}
Assumptions / limitations
- swagger file is in version 2 format, it must be json
- each endpoint must have a
tags
attribute defined. In addition, there must be exactly one tag defined. The http methods are grouped to services based on the tags, i.e. if two methods have tag "order", both will be generated inside Order.ts get
anddelete
methods do not containbody
- swagger file should contain values for the keys
host
andbasePath
so that each generated service method can contain a link to the swagger UI method reference, e.g.http://example.com/swagger/swagger-ui.html#!/Order/Order
definitions
section in swagger file does not contain types with inline definitions, i.e. only named subtypes work
Usage of NGRX modules
Development
- developed with node v16
Docker image
docker build . -t angular-swagger2
docker run -u $(id -u) -it -v "$PWD":/code angular-swagger2 bash
npm i
npm run install:demo
Testing
How the testing works
- tests are written in the demo-app
- the test swagger files can be found in demo-app/client/test-swaggers
- upon these swagger files, interfaces and services are generated
- the generated services are manually imported to the app.module.ts
- unit tests can be found in demo-app/client/src/tests
Running the tests
To run client tests in interactive mode:
cd demo-app/client
npm test
Release
git checkout -b tech/release
on master or other branch you want to releasenpm version patch
or other version change you want- make a PR
- once merged
npm publish
Pull requests are welcome!
Please do the following before making a PR:
- Build the app and regenerate testing files via
npm run build
. - Check test pass via
npm test
. - Check files lint via
npm run lint
.