[Feature][Angular] improve docs angular import (#7363)

* #7354: improve docs about importing multiple ApiModules, prevent https://github.com/angular/angular/issues/20575#issuecomment-356261374

* #7354: prevent https://github.com/angular/angular/issues/20575#issuecomment-356261374 add error message about importing the HttpModule / HttpClientModule

* #7354: generate sample files

* #7354: generate README.md also for non-npm packages

modules/swagger-codegen/src/main/java/io/swagger/codegen/languages/TypeScriptAngularClientCodegen.java

@@ -93,6 +93,7 @@ public class TypeScriptAngularClientCodegen extends AbstractTypeScriptClientCode
         supportingFiles.add(new SupportingFile("encoder.mustache", getIndexDirectory(), "encoder.ts"));
         supportingFiles.add(new SupportingFile("gitignore", "", ".gitignore"));
         supportingFiles.add(new SupportingFile("git_push.sh.mustache", "", "git_push.sh"));
+        supportingFiles.add(new SupportingFile("README.mustache", getIndexDirectory(), "README.md"));
 
         if (additionalProperties.containsKey(NPM_NAME)) {
             addNpmPackageGeneration();
@@ -143,7 +144,6 @@ public class TypeScriptAngularClientCodegen extends AbstractTypeScriptClientCode
         }
 
         //Files for building our lib
-        supportingFiles.add(new SupportingFile("README.mustache", getIndexDirectory(), "README.md"));
         supportingFiles.add(new SupportingFile("package.mustache", getIndexDirectory(), "package.json"));
         supportingFiles.add(new SupportingFile("typings.mustache", getIndexDirectory(), "typings.json"));
         supportingFiles.add(new SupportingFile("tsconfig.mustache", getIndexDirectory(), "tsconfig.json"));

modules/swagger-codegen/src/main/resources/typescript-angular/README.mustache

@@ -46,9 +46,16 @@ In your Angular project:
 ```
 // without configuring providers
 import { ApiModule } from '{{npmName}}';
+{{#useHttpClient}}import { HttpClientModule } from '@angular/common/http';{{/useHttpClient}}
+{{^useHttpClient}}import { HttpModule } from '@angular/http';{{/useHttpClient}}
 
 @NgModule({
-    imports: [ ApiModule ],
+    imports: [
+        ApiModule,
+        {{#useHttpClient}}// make sure to import the HttpClientModule in the AppModule only,
+        // see https://github.com/angular/angular/issues/20575
+        HttpClientModule{{/useHttpClient}}{{^useHttpClient}}HttpModule{{/useHttpClient}}
+    ],
     declarations: [ AppComponent ],
     providers: [],
     bootstrap: [ AppComponent ]
@@ -87,6 +94,31 @@ export class AppComponent {
 Note: The ApiModule is restricted to being instantiated once app wide.
 This is to ensure that all services are treated as singletons.
 
+#### Using multiple swagger files / APIs / ApiModules
+In order to use multiple `ApiModules` generated from different swagger files,
+you can create an alias name when importing the modules
+in order to avoid naming conflicts:
+```
+import { ApiModule } from 'my-api-path';
+import { ApiModule as OtherApiModule } from 'my-other-api-path';
+{{#useHttpClient}}import { HttpClientModule } from '@angular/common/http';{{/useHttpClient}}
+{{^useHttpClient}}import { HttpModule } from '@angular/http';{{/useHttpClient}}
+
+@NgModule({
+  imports: [
+    ApiModule,
+    OtherApiModule,
+    {{#useHttpClient}}// make sure to import the HttpClientModule in the AppModule only,
+    // see https://github.com/angular/angular/issues/20575
+    HttpClientModule{{/useHttpClient}}{{^useHttpClient}}HttpModule{{/useHttpClient}}
+  ]
+})
+export class AppModule {
+
+}
+```
+
+
 ### Set service base path
 If different than the generated base path, during app bootstrap, you can provide the base path to your service. 
 

modules/swagger-codegen/src/main/resources/typescript-angular/api.module.mustache

@@ -1,12 +1,7 @@
 import { NgModule, ModuleWithProviders, SkipSelf, Optional } from '@angular/core';
-import { CommonModule } from '@angular/common';
-{{#useHttpClient}}
-import { HttpClientModule } from '@angular/common/http';
-{{/useHttpClient}}
-{{^useHttpClient}}
-import { HttpModule } from '@angular/http';
-{{/useHttpClient}}
 import { Configuration } from './configuration';
+{{#useHttpClient}}import { HttpClient } from '@angular/common/http';{{/useHttpClient}}
+{{^useHttpClient}}import { Http } from '@angular/http';{{/useHttpClient}}
 
 {{#apiInfo}}
 {{#apis}}
@@ -15,7 +10,7 @@ import { {{classname}} } from './{{importPath}}';
 {{/apiInfo}}
 
 @NgModule({
-  imports:      [ CommonModule, {{#useHttpClient}}HttpClientModule{{/useHttpClient}}{{^useHttpClient}}HttpModule{{/useHttpClient}} ],
+  imports:      [],
   declarations: [],
   exports:      [],
   providers: [
@@ -30,9 +25,14 @@ export class ApiModule {
         }
     }
 
-    constructor( @Optional() @SkipSelf() parentModule: ApiModule) {
+    constructor( @Optional() @SkipSelf() parentModule: ApiModule,
+                 @Optional() http: {{#useHttpClient}}HttpClient{{/useHttpClient}}{{^useHttpClient}}Http{{/useHttpClient}}) {
         if (parentModule) {
-            throw new Error('ApiModule is already loaded. Import your base AppModule only.');
+            throw new Error('ApiModule is already loaded. Import in your base AppModule only.');
+        }
+        if (!http) {
+            throw new Error('You need to import the {{#useHttpClient}}HttpClientModule{{/useHttpClient}}{{^useHttpClient}}HttpModule{{/useHttpClient}} in your AppModule! \n' +
+            'See also https://github.com/angular/angular/issues/20575');
         }
     }
 }

samples/client/petstore/typescript-angular-v2/default/.swagger-codegen/VERSION

@@ -1 +1 @@
-2.3.0
+2.3.1-SNAPSHOT

samples/client/petstore/typescript-angular-v2/default/README.md

@@ -0,0 +1,167 @@
+## @
+
+### Building
+
+To build an compile the typescript sources to javascript use:
+```
+npm install
+npm run build
+```
+
+### publishing
+
+First build the package than run ```npm publish```
+
+### consuming
+
+navigate to the folder of your consuming project and run one of next commando's.
+
+_published:_
+
+```
+npm install @ --save
+```
+
+_unPublished (not recommended):_
+
+```
+npm install PATH_TO_GENERATED_PACKAGE --save
+```
+
+_using `npm link`:_
+
+In PATH_TO_GENERATED_PACKAGE:
+```
+npm link
+```
+
+In your project:
+```
+npm link @
+```
+
+In your Angular project:
+
+
+```
+// without configuring providers
+import { ApiModule } from '';
+
+import { HttpModule } from '@angular/http';
+
+@NgModule({
+    imports: [
+        ApiModule,
+        HttpModule
+    ],
+    declarations: [ AppComponent ],
+    providers: [],
+    bootstrap: [ AppComponent ]
+})
+export class AppModule {}
+```
+
+```
+// configuring providers
+import { ApiModule, Configuration, ConfigurationParameters } from '';
+
+export function apiConfigFactory (): Configuration => {
+  const params: ConfigurationParameters = {
+    // set configuration parameters here.
+  }
+  return new Configuration(params);
+}
+
+@NgModule({
+    imports: [ ApiModule.forRoot(apiConfigFactory) ],
+    declarations: [ AppComponent ],
+    providers: [],
+    bootstrap: [ AppComponent ]
+})
+export class AppModule {}
+```
+
+```
+import { DefaultApi } from '';
+
+export class AppComponent {
+	 constructor(private apiGateway: DefaultApi) { }
+}
+```
+
+Note: The ApiModule is restricted to being instantiated once app wide.
+This is to ensure that all services are treated as singletons.
+
+#### Using multiple swagger files / APIs / ApiModules
+In order to use multiple `ApiModules` generated from different swagger files,
+you can create an alias name when importing the modules
+in order to avoid naming conflicts:
+```
+import { ApiModule } from 'my-api-path';
+import { ApiModule as OtherApiModule } from 'my-other-api-path';
+
+import { HttpModule } from '@angular/http';
+
+@NgModule({
+  imports: [
+    ApiModule,
+    OtherApiModule,
+    HttpModule
+  ]
+})
+export class AppModule {
+
+}
+```
+
+
+### Set service base path
+If different than the generated base path, during app bootstrap, you can provide the base path to your service. 
+
+```
+import { BASE_PATH } from '';
+
+bootstrap(AppComponent, [
+    { provide: BASE_PATH, useValue: 'https://your-web-service.com' },
+]);
+```
+or
+
+```
+import { BASE_PATH } from '';
+
+@NgModule({
+    imports: [],
+    declarations: [ AppComponent ],
+    providers: [ provide: BASE_PATH, useValue: 'https://your-web-service.com' ],
+    bootstrap: [ AppComponent ]
+})
+export class AppModule {}
+```
+
+
+#### Using @angular/cli
+First extend your `src/environments/*.ts` files by adding the corresponding base path:
+
+```
+export const environment = {
+  production: false,
+  API_BASE_PATH: 'http://127.0.0.1:8080'
+};
+```
+
+In the src/app/app.module.ts:
+```
+import { BASE_PATH } from '';
+import { environment } from '../environments/environment';
+
+@NgModule({
+  declarations: [
+    AppComponent
+  ],
+  imports: [ ],
+  providers: [{ provide: BASE_PATH, useValue: environment.API_BASE_PATH }],
+  bootstrap: [ AppComponent ]
+})
+export class AppModule { }
+```  

samples/client/petstore/typescript-angular-v2/default/api.module.ts

@@ -1,14 +1,14 @@
 import { NgModule, ModuleWithProviders, SkipSelf, Optional } from '@angular/core';
-import { CommonModule } from '@angular/common';
-import { HttpModule } from '@angular/http';
 import { Configuration } from './configuration';
 
+import { Http } from '@angular/http';
+
 import { PetService } from './api/pet.service';
 import { StoreService } from './api/store.service';
 import { UserService } from './api/user.service';
 
 @NgModule({
-  imports:      [ CommonModule, HttpModule ],
+  imports:      [],
   declarations: [],
   exports:      [],
   providers: [
@@ -24,9 +24,14 @@ export class ApiModule {
         }
     }
 
-    constructor( @Optional() @SkipSelf() parentModule: ApiModule) {
+    constructor( @Optional() @SkipSelf() parentModule: ApiModule,
+                 @Optional() http: Http) {
         if (parentModule) {
-            throw new Error('ApiModule is already loaded. Import your base AppModule only.');
+            throw new Error('ApiModule is already loaded. Import in your base AppModule only.');
+        }
+        if (!http) {
+            throw new Error('You need to import the HttpModule in your AppModule! \n' +
+            'See also https://github.com/angular/angular/issues/20575');
         }
     }
 }

samples/client/petstore/typescript-angular-v2/npm/.swagger-codegen/VERSION

@@ -1 +1 @@
-2.3.0
+2.3.1-SNAPSHOT

samples/client/petstore/typescript-angular-v2/npm/README.md

@@ -47,8 +47,13 @@ In your Angular project:
 // without configuring providers
 import { ApiModule } from '@swagger/angular2-typescript-petstore';
 
+import { HttpModule } from '@angular/http';
+
 @NgModule({
-    imports: [ ApiModule ],
+    imports: [
+        ApiModule,
+        HttpModule
+    ],
     declarations: [ AppComponent ],
     providers: [],
     bootstrap: [ AppComponent ]
@@ -87,6 +92,29 @@ export class AppComponent {
 Note: The ApiModule is restricted to being instantiated once app wide.
 This is to ensure that all services are treated as singletons.
 
+#### Using multiple swagger files / APIs / ApiModules
+In order to use multiple `ApiModules` generated from different swagger files,
+you can create an alias name when importing the modules
+in order to avoid naming conflicts:
+```
+import { ApiModule } from 'my-api-path';
+import { ApiModule as OtherApiModule } from 'my-other-api-path';
+
+import { HttpModule } from '@angular/http';
+
+@NgModule({
+  imports: [
+    ApiModule,
+    OtherApiModule,
+    HttpModule
+  ]
+})
+export class AppModule {
+
+}
+```
+
+
 ### Set service base path
 If different than the generated base path, during app bootstrap, you can provide the base path to your service. 
 

samples/client/petstore/typescript-angular-v2/npm/api.module.ts

@@ -1,6 +1,5 @@
 import { NgModule, ModuleWithProviders, SkipSelf, Optional } from '@angular/core';
 import { CommonModule } from '@angular/common';
-import { HttpModule } from '@angular/http';
 import { Configuration } from './configuration';
 
 import { PetService } from './api/pet.service';
@@ -8,7 +7,7 @@ import { StoreService } from './api/store.service';
 import { UserService } from './api/user.service';
 
 @NgModule({
-  imports:      [ CommonModule, HttpModule ],
+  imports:      [],
   declarations: [],
   exports:      [],
   providers: [
@@ -26,7 +25,7 @@ export class ApiModule {
 
     constructor( @Optional() @SkipSelf() parentModule: ApiModule) {
         if (parentModule) {
-            throw new Error('ApiModule is already loaded. Import your base AppModule only.');
+            throw new Error('ApiModule is already loaded. Import in your base AppModule only.');
         }
     }
 }

samples/client/petstore/typescript-angular-v2/with-interfaces/.swagger-codegen/VERSION

@@ -1 +1 @@
-2.3.0
+2.3.1-SNAPSHOT

samples/client/petstore/typescript-angular-v2/with-interfaces/README.md

@@ -47,8 +47,13 @@ In your Angular project:
 // without configuring providers
 import { ApiModule } from '@swagger/angular2-typescript-petstore';
 
+import { HttpModule } from '@angular/http';
+
 @NgModule({
-    imports: [ ApiModule ],
+    imports: [
+        ApiModule,
+        HttpModule
+    ],
     declarations: [ AppComponent ],
     providers: [],
     bootstrap: [ AppComponent ]
@@ -87,6 +92,29 @@ export class AppComponent {
 Note: The ApiModule is restricted to being instantiated once app wide.
 This is to ensure that all services are treated as singletons.
 
+#### Using multiple swagger files / APIs / ApiModules
+In order to use multiple `ApiModules` generated from different swagger files,
+you can create an alias name when importing the modules
+in order to avoid naming conflicts:
+```
+import { ApiModule } from 'my-api-path';
+import { ApiModule as OtherApiModule } from 'my-other-api-path';
+
+import { HttpModule } from '@angular/http';
+
+@NgModule({
+  imports: [
+    ApiModule,
+    OtherApiModule,
+    HttpModule
+  ]
+})
+export class AppModule {
+
+}
+```
+
+
 ### Set service base path
 If different than the generated base path, during app bootstrap, you can provide the base path to your service. 
 

samples/client/petstore/typescript-angular-v2/with-interfaces/api.module.ts

@@ -1,14 +1,14 @@
 import { NgModule, ModuleWithProviders, SkipSelf, Optional } from '@angular/core';
-import { CommonModule } from '@angular/common';
-import { HttpModule } from '@angular/http';
 import { Configuration } from './configuration';
 
+import { Http } from '@angular/http';
+
 import { PetService } from './api/pet.service';
 import { StoreService } from './api/store.service';
 import { UserService } from './api/user.service';
 
 @NgModule({
-  imports:      [ CommonModule, HttpModule ],
+  imports:      [],
   declarations: [],
   exports:      [],
   providers: [
@@ -24,9 +24,14 @@ export class ApiModule {
         }
     }
 
-    constructor( @Optional() @SkipSelf() parentModule: ApiModule) {
+    constructor( @Optional() @SkipSelf() parentModule: ApiModule,
+                 @Optional() http: Http) {
         if (parentModule) {
-            throw new Error('ApiModule is already loaded. Import your base AppModule only.');
+            throw new Error('ApiModule is already loaded. Import in your base AppModule only.');
+        }
+        if (!http) {
+            throw new Error('You need to import the HttpModule in your AppModule! \n' +
+            'See also https://github.com/angular/angular/issues/20575');
         }
     }
 }

samples/client/petstore/typescript-angular-v4.3/npm/.swagger-codegen/VERSION

@@ -1 +1 @@
-2.3.0
+2.3.1-SNAPSHOT

samples/client/petstore/typescript-angular-v4.3/npm/README.md

@@ -46,9 +46,16 @@ In your Angular project:
 ```
 // without configuring providers
 import { ApiModule } from '@swagger/angular2-typescript-petstore';
+import { HttpClientModule } from '@angular/common/http';
+
 
 @NgModule({
-    imports: [ ApiModule ],
+    imports: [
+        ApiModule,
+        // make sure to import the HttpClientModule in the AppModule only,
+        // see https://github.com/angular/angular/issues/20575
+        HttpClientModule
+    ],
     declarations: [ AppComponent ],
     providers: [],
     bootstrap: [ AppComponent ]
@@ -87,6 +94,31 @@ export class AppComponent {
 Note: The ApiModule is restricted to being instantiated once app wide.
 This is to ensure that all services are treated as singletons.
 
+#### Using multiple swagger files / APIs / ApiModules
+In order to use multiple `ApiModules` generated from different swagger files,
+you can create an alias name when importing the modules
+in order to avoid naming conflicts:
+```
+import { ApiModule } from 'my-api-path';
+import { ApiModule as OtherApiModule } from 'my-other-api-path';
+import { HttpClientModule } from '@angular/common/http';
+
+
+@NgModule({
+  imports: [
+    ApiModule,
+    OtherApiModule,
+    // make sure to import the HttpClientModule in the AppModule only,
+    // see https://github.com/angular/angular/issues/20575
+    HttpClientModule
+  ]
+})
+export class AppModule {
+
+}
+```
+
+
 ### Set service base path
 If different than the generated base path, during app bootstrap, you can provide the base path to your service. 
 

samples/client/petstore/typescript-angular-v4.3/npm/api.module.ts

@@ -1,14 +1,14 @@
 import { NgModule, ModuleWithProviders, SkipSelf, Optional } from '@angular/core';
-import { CommonModule } from '@angular/common';
-import { HttpClientModule } from '@angular/common/http';
 import { Configuration } from './configuration';
+import { HttpClient } from '@angular/common/http';
+
 
 import { PetService } from './api/pet.service';
 import { StoreService } from './api/store.service';
 import { UserService } from './api/user.service';
 
 @NgModule({
-  imports:      [ CommonModule, HttpClientModule ],
+  imports:      [],
   declarations: [],
   exports:      [],
   providers: [
@@ -24,9 +24,14 @@ export class ApiModule {
         }
     }
 
-    constructor( @Optional() @SkipSelf() parentModule: ApiModule) {
+    constructor( @Optional() @SkipSelf() parentModule: ApiModule,
+                 @Optional() http: HttpClient) {
         if (parentModule) {
-            throw new Error('ApiModule is already loaded. Import your base AppModule only.');
+            throw new Error('ApiModule is already loaded. Import in your base AppModule only.');
+        }
+        if (!http) {
+            throw new Error('You need to import the HttpClientModule in your AppModule! \n' +
+            'See also https://github.com/angular/angular/issues/20575');
         }
     }
 }

samples/client/petstore/typescript-angular-v4.3/npm/rxjs-operators.ts

@@ -0,0 +1,11 @@
+// RxJS imports according to https://angular.io/docs/ts/latest/guide/server-communication.html#!#rxjs
+
+// See node_module/rxjs/Rxjs.js
+// Import just the rxjs statics and operators we need for THIS app.
+
+// Statics
+import 'rxjs/add/observable/throw';
+
+// Operators
+import 'rxjs/add/operator/catch';
+import 'rxjs/add/operator/map';

samples/client/petstore/typescript-angular-v4/npm/.swagger-codegen/VERSION

@@ -1 +1 @@
-2.3.0
+2.3.1-SNAPSHOT

samples/client/petstore/typescript-angular-v4/npm/README.md

@@ -47,8 +47,13 @@ In your Angular project:
 // without configuring providers
 import { ApiModule } from '@swagger/angular2-typescript-petstore';
 
+import { HttpModule } from '@angular/http';
+
 @NgModule({
-    imports: [ ApiModule ],
+    imports: [
+        ApiModule,
+        HttpModule
+    ],
     declarations: [ AppComponent ],
     providers: [],
     bootstrap: [ AppComponent ]
@@ -87,6 +92,29 @@ export class AppComponent {
 Note: The ApiModule is restricted to being instantiated once app wide.
 This is to ensure that all services are treated as singletons.
 
+#### Using multiple swagger files / APIs / ApiModules
+In order to use multiple `ApiModules` generated from different swagger files,
+you can create an alias name when importing the modules
+in order to avoid naming conflicts:
+```
+import { ApiModule } from 'my-api-path';
+import { ApiModule as OtherApiModule } from 'my-other-api-path';
+
+import { HttpModule } from '@angular/http';
+
+@NgModule({
+  imports: [
+    ApiModule,
+    OtherApiModule,
+    HttpModule
+  ]
+})
+export class AppModule {
+
+}
+```
+
+
 ### Set service base path
 If different than the generated base path, during app bootstrap, you can provide the base path to your service. 
 

samples/client/petstore/typescript-angular-v4/npm/api.module.ts

@@ -1,14 +1,14 @@
 import { NgModule, ModuleWithProviders, SkipSelf, Optional } from '@angular/core';
-import { CommonModule } from '@angular/common';
-import { HttpModule } from '@angular/http';
 import { Configuration } from './configuration';
 
+import { Http } from '@angular/http';
+
 import { PetService } from './api/pet.service';
 import { StoreService } from './api/store.service';
 import { UserService } from './api/user.service';
 
 @NgModule({
-  imports:      [ CommonModule, HttpModule ],
+  imports:      [],
   declarations: [],
   exports:      [],
   providers: [
@@ -24,9 +24,14 @@ export class ApiModule {
         }
     }
 
-    constructor( @Optional() @SkipSelf() parentModule: ApiModule) {
+    constructor( @Optional() @SkipSelf() parentModule: ApiModule,
+                 @Optional() http: Http) {
         if (parentModule) {
-            throw new Error('ApiModule is already loaded. Import your base AppModule only.');
+            throw new Error('ApiModule is already loaded. Import in your base AppModule only.');
+        }
+        if (!http) {
+            throw new Error('You need to import the HttpModule in your AppModule! \n' +
+            'See also https://github.com/angular/angular/issues/20575');
         }
     }
 }