Purpose

Generate minimalistic TypeScript API layer with full type reflection of backend model.

• Source: swagger scheme
• Destination: Angular-cli based Angular app.

Install

1. npm i swagger-angular-generator --save-dev
2. check usage via ./node_modules/.bin/swagger-angular-generator -h

Use

Run generator

1. get the swagger scheme at http(s)://domain/[path]/v2/api/api-docs
2. save it to json file in input directory and format it
3. run via
   1. directly ./node_modules/.bin/swagger-angular-generator
   2. as module swagger-angular-generator package, npm run generate

      "script": {
        "generate": "swagger-angular-generator -s src/api/scheme.json -d src/api/generated"
        ...
      }

   3. or programatically as a method invocation

      import {generate} from 'swagger-angular-generator';
      // or using CommonJS loader
      const {generate} = require('swagger-angular-generator');
      
      generate('conf/api/api-docs.json', 'src/api');

The resulting API layer contains the following structure in the destination directory:

1. def directory stores all response interfaces and enums
2. model.ts file reexports all of them together for a simple access
3. api directory stores services devided by controllers containing all API methods

When updating your code for new backend version, follow these steps:

1. git diff the changes
2. run tsc for immediate problems
3. adjust the code, solve problems
4. commit

Use

In order to consume generated model, follow the steps 1-9 in the following example to use generated API model.

Getting ready for injection in the module

// 1. add providers to your module, e.g.
import {ApiService} from '../api/services/api';
import {AuthService} from '../api/services/auth';

@NgModule({providers: [ApiService, AuthService, ...], ...})
export class AppModule {}

Usage in the service or component

// 2. import used response types
import {ItemDto, PageDto} from '[relative-path-to-destination-directory]/model';
// 3. import used controller service and optionally param types
import {DataService, MethodParams} from '[relative-path-to-destination-directory]/api/DataService';

@Component({
  // 4. enable injection
  providers: [DataService]
})
export class MyComponent implements OnInit {
  // 5. link response objects to generated API types
  public items: ItemDto[] = [];
  public page: PageDto;

  // 6. link request params to generated API types (all params are passed together in one object)
  private params: MethodParams = {
    page: 0,
    size: 10,
    sort: ['name:asc']
  };

  // 7. inject the service
  constructor(private dataService: DataService) {}

  public ngOnInit() {
    // 8. the returned observable is fully typed
    this.dataService
      .get(this.params)
      // 9. returned data are fully typed
      .subscribe(data => {
        // 10. assignments type-checked
        const {content, page} = data;
        this.items = content;
        this.page = page;
      });
  }
}

Known limitations / specifics

1. ignoring params (on purpose)
   1. header globally
   2. body for get and delete