Skip to content

Commit ef832e7

Browse files
macjohnnywing328
macjohnny
authored and
wing328
committed
[Feature][Angular] improve docs angular import (#7363)
* #7354: improve docs about importing multiple ApiModules, prevent angular/angular#20575 (comment) * #7354: prevent angular/angular#20575 (comment) add error message about importing the HttpModule / HttpClientModule * #7354: generate sample files * #7354: generate README.md also for non-npm packages
1 parent 197b448 commit ef832e7

File tree

19 files changed

+389
-44
lines changed

19 files changed

+389
-44
lines changed

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,7 @@ public void processOpts() {
9393
supportingFiles.add(new SupportingFile("encoder.mustache", getIndexDirectory(), "encoder.ts"));
9494
supportingFiles.add(new SupportingFile("gitignore", "", ".gitignore"));
9595
supportingFiles.add(new SupportingFile("git_push.sh.mustache", "", "git_push.sh"));
96+
supportingFiles.add(new SupportingFile("README.mustache", getIndexDirectory(), "README.md"));
9697

9798
if (additionalProperties.containsKey(NPM_NAME)) {
9899
addNpmPackageGeneration();
@@ -143,7 +144,6 @@ private void addNpmPackageGeneration() {
143144
}
144145

145146
//Files for building our lib
146-
supportingFiles.add(new SupportingFile("README.mustache", getIndexDirectory(), "README.md"));
147147
supportingFiles.add(new SupportingFile("package.mustache", getIndexDirectory(), "package.json"));
148148
supportingFiles.add(new SupportingFile("typings.mustache", getIndexDirectory(), "typings.json"));
149149
supportingFiles.add(new SupportingFile("tsconfig.mustache", getIndexDirectory(), "tsconfig.json"));

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

Lines changed: 33 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,9 +46,16 @@ In your Angular project:
4646
```
4747
// without configuring providers
4848
import { ApiModule } from '{{npmName}}';
49+
{{#useHttpClient}}import { HttpClientModule } from '@angular/common/http';{{/useHttpClient}}
50+
{{^useHttpClient}}import { HttpModule } from '@angular/http';{{/useHttpClient}}
4951

5052
@NgModule({
51-
imports: [ ApiModule ],
53+
imports: [
54+
ApiModule,
55+
{{#useHttpClient}}// make sure to import the HttpClientModule in the AppModule only,
56+
// see https://github.com/angular/angular/issues/20575
57+
HttpClientModule{{/useHttpClient}}{{^useHttpClient}}HttpModule{{/useHttpClient}}
58+
],
5259
declarations: [ AppComponent ],
5360
providers: [],
5461
bootstrap: [ AppComponent ]
@@ -87,6 +94,31 @@ export class AppComponent {
8794
Note: The ApiModule is restricted to being instantiated once app wide.
8895
This is to ensure that all services are treated as singletons.
8996

97+
#### Using multiple swagger files / APIs / ApiModules
98+
In order to use multiple `ApiModules` generated from different swagger files,
99+
you can create an alias name when importing the modules
100+
in order to avoid naming conflicts:
101+
```
102+
import { ApiModule } from 'my-api-path';
103+
import { ApiModule as OtherApiModule } from 'my-other-api-path';
104+
{{#useHttpClient}}import { HttpClientModule } from '@angular/common/http';{{/useHttpClient}}
105+
{{^useHttpClient}}import { HttpModule } from '@angular/http';{{/useHttpClient}}
106+
107+
@NgModule({
108+
imports: [
109+
ApiModule,
110+
OtherApiModule,
111+
{{#useHttpClient}}// make sure to import the HttpClientModule in the AppModule only,
112+
// see https://github.com/angular/angular/issues/20575
113+
HttpClientModule{{/useHttpClient}}{{^useHttpClient}}HttpModule{{/useHttpClient}}
114+
]
115+
})
116+
export class AppModule {
117+
118+
}
119+
```
120+
121+
90122
### Set service base path
91123
If different than the generated base path, during app bootstrap, you can provide the base path to your service.
92124

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

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,7 @@
11
import { NgModule, ModuleWithProviders, SkipSelf, Optional } from '@angular/core';
2-
import { CommonModule } from '@angular/common';
3-
{{#useHttpClient}}
4-
import { HttpClientModule } from '@angular/common/http';
5-
{{/useHttpClient}}
6-
{{^useHttpClient}}
7-
import { HttpModule } from '@angular/http';
8-
{{/useHttpClient}}
92
import { Configuration } from './configuration';
3+
{{#useHttpClient}}import { HttpClient } from '@angular/common/http';{{/useHttpClient}}
4+
{{^useHttpClient}}import { Http } from '@angular/http';{{/useHttpClient}}
105

116
{{#apiInfo}}
127
{{#apis}}
@@ -15,7 +10,7 @@ import { {{classname}} } from './{{importPath}}';
1510
{{/apiInfo}}
1611

1712
@NgModule({
18-
imports: [ CommonModule, {{#useHttpClient}}HttpClientModule{{/useHttpClient}}{{^useHttpClient}}HttpModule{{/useHttpClient}} ],
13+
imports: [],
1914
declarations: [],
2015
exports: [],
2116
providers: [
@@ -30,9 +25,14 @@ export class ApiModule {
3025
}
3126
}
3227

33-
constructor( @Optional() @SkipSelf() parentModule: ApiModule) {
28+
constructor( @Optional() @SkipSelf() parentModule: ApiModule,
29+
@Optional() http: {{#useHttpClient}}HttpClient{{/useHttpClient}}{{^useHttpClient}}Http{{/useHttpClient}}) {
3430
if (parentModule) {
35-
throw new Error('ApiModule is already loaded. Import your base AppModule only.');
31+
throw new Error('ApiModule is already loaded. Import in your base AppModule only.');
32+
}
33+
if (!http) {
34+
throw new Error('You need to import the {{#useHttpClient}}HttpClientModule{{/useHttpClient}}{{^useHttpClient}}HttpModule{{/useHttpClient}} in your AppModule! \n' +
35+
'See also https://github.com/angular/angular/issues/20575');
3636
}
3737
}
3838
}

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
2.3.0
1+
2.3.1-SNAPSHOT

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

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
## @
2+
3+
### Building
4+
5+
To build an compile the typescript sources to javascript use:
6+
```
7+
npm install
8+
npm run build
9+
```
10+
11+
### publishing
12+
13+
First build the package than run ```npm publish```
14+
15+
### consuming
16+
17+
navigate to the folder of your consuming project and run one of next commando's.
18+
19+
_published:_
20+
21+
```
22+
npm install @ --save
23+
```
24+
25+
_unPublished (not recommended):_
26+
27+
```
28+
npm install PATH_TO_GENERATED_PACKAGE --save
29+
```
30+
31+
_using `npm link`:_
32+
33+
In PATH_TO_GENERATED_PACKAGE:
34+
```
35+
npm link
36+
```
37+
38+
In your project:
39+
```
40+
npm link @
41+
```
42+
43+
In your Angular project:
44+
45+
46+
```
47+
// without configuring providers
48+
import { ApiModule } from '';
49+
50+
import { HttpModule } from '@angular/http';
51+
52+
@NgModule({
53+
imports: [
54+
ApiModule,
55+
HttpModule
56+
],
57+
declarations: [ AppComponent ],
58+
providers: [],
59+
bootstrap: [ AppComponent ]
60+
})
61+
export class AppModule {}
62+
```
63+
64+
```
65+
// configuring providers
66+
import { ApiModule, Configuration, ConfigurationParameters } from '';
67+
68+
export function apiConfigFactory (): Configuration => {
69+
const params: ConfigurationParameters = {
70+
// set configuration parameters here.
71+
}
72+
return new Configuration(params);
73+
}
74+
75+
@NgModule({
76+
imports: [ ApiModule.forRoot(apiConfigFactory) ],
77+
declarations: [ AppComponent ],
78+
providers: [],
79+
bootstrap: [ AppComponent ]
80+
})
81+
export class AppModule {}
82+
```
83+
84+
```
85+
import { DefaultApi } from '';
86+
87+
export class AppComponent {
88+
constructor(private apiGateway: DefaultApi) { }
89+
}
90+
```
91+
92+
Note: The ApiModule is restricted to being instantiated once app wide.
93+
This is to ensure that all services are treated as singletons.
94+
95+
#### Using multiple swagger files / APIs / ApiModules
96+
In order to use multiple `ApiModules` generated from different swagger files,
97+
you can create an alias name when importing the modules
98+
in order to avoid naming conflicts:
99+
```
100+
import { ApiModule } from 'my-api-path';
101+
import { ApiModule as OtherApiModule } from 'my-other-api-path';
102+
103+
import { HttpModule } from '@angular/http';
104+
105+
@NgModule({
106+
imports: [
107+
ApiModule,
108+
OtherApiModule,
109+
HttpModule
110+
]
111+
})
112+
export class AppModule {
113+
114+
}
115+
```
116+
117+
118+
### Set service base path
119+
If different than the generated base path, during app bootstrap, you can provide the base path to your service.
120+
121+
```
122+
import { BASE_PATH } from '';
123+
124+
bootstrap(AppComponent, [
125+
{ provide: BASE_PATH, useValue: 'https://your-web-service.com' },
126+
]);
127+
```
128+
or
129+
130+
```
131+
import { BASE_PATH } from '';
132+
133+
@NgModule({
134+
imports: [],
135+
declarations: [ AppComponent ],
136+
providers: [ provide: BASE_PATH, useValue: 'https://your-web-service.com' ],
137+
bootstrap: [ AppComponent ]
138+
})
139+
export class AppModule {}
140+
```
141+
142+
143+
#### Using @angular/cli
144+
First extend your `src/environments/*.ts` files by adding the corresponding base path:
145+
146+
```
147+
export const environment = {
148+
production: false,
149+
API_BASE_PATH: 'http://127.0.0.1:8080'
150+
};
151+
```
152+
153+
In the src/app/app.module.ts:
154+
```
155+
import { BASE_PATH } from '';
156+
import { environment } from '../environments/environment';
157+
158+
@NgModule({
159+
declarations: [
160+
AppComponent
161+
],
162+
imports: [ ],
163+
providers: [{ provide: BASE_PATH, useValue: environment.API_BASE_PATH }],
164+
bootstrap: [ AppComponent ]
165+
})
166+
export class AppModule { }
167+
```

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

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
import { NgModule, ModuleWithProviders, SkipSelf, Optional } from '@angular/core';
2-
import { CommonModule } from '@angular/common';
3-
import { HttpModule } from '@angular/http';
42
import { Configuration } from './configuration';
53

4+
import { Http } from '@angular/http';
5+
66
import { PetService } from './api/pet.service';
77
import { StoreService } from './api/store.service';
88
import { UserService } from './api/user.service';
99

1010
@NgModule({
11-
imports: [ CommonModule, HttpModule ],
11+
imports: [],
1212
declarations: [],
1313
exports: [],
1414
providers: [
@@ -24,9 +24,14 @@ export class ApiModule {
2424
}
2525
}
2626

27-
constructor( @Optional() @SkipSelf() parentModule: ApiModule) {
27+
constructor( @Optional() @SkipSelf() parentModule: ApiModule,
28+
@Optional() http: Http) {
2829
if (parentModule) {
29-
throw new Error('ApiModule is already loaded. Import your base AppModule only.');
30+
throw new Error('ApiModule is already loaded. Import in your base AppModule only.');
31+
}
32+
if (!http) {
33+
throw new Error('You need to import the HttpModule in your AppModule! \n' +
34+
'See also https://github.com/angular/angular/issues/20575');
3035
}
3136
}
3237
}

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
2.3.0
1+
2.3.1-SNAPSHOT

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

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,8 +47,13 @@ In your Angular project:
4747
// without configuring providers
4848
import { ApiModule } from '@swagger/angular2-typescript-petstore';
4949
50+
import { HttpModule } from '@angular/http';
51+
5052
@NgModule({
51-
imports: [ ApiModule ],
53+
imports: [
54+
ApiModule,
55+
HttpModule
56+
],
5257
declarations: [ AppComponent ],
5358
providers: [],
5459
bootstrap: [ AppComponent ]
@@ -87,6 +92,29 @@ export class AppComponent {
8792
Note: The ApiModule is restricted to being instantiated once app wide.
8893
This is to ensure that all services are treated as singletons.
8994

95+
#### Using multiple swagger files / APIs / ApiModules
96+
In order to use multiple `ApiModules` generated from different swagger files,
97+
you can create an alias name when importing the modules
98+
in order to avoid naming conflicts:
99+
```
100+
import { ApiModule } from 'my-api-path';
101+
import { ApiModule as OtherApiModule } from 'my-other-api-path';
102+
103+
import { HttpModule } from '@angular/http';
104+
105+
@NgModule({
106+
imports: [
107+
ApiModule,
108+
OtherApiModule,
109+
HttpModule
110+
]
111+
})
112+
export class AppModule {
113+
114+
}
115+
```
116+
117+
90118
### Set service base path
91119
If different than the generated base path, during app bootstrap, you can provide the base path to your service.
92120

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

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,13 @@
11
import { NgModule, ModuleWithProviders, SkipSelf, Optional } from '@angular/core';
22
import { CommonModule } from '@angular/common';
3-
import { HttpModule } from '@angular/http';
43
import { Configuration } from './configuration';
54

65
import { PetService } from './api/pet.service';
76
import { StoreService } from './api/store.service';
87
import { UserService } from './api/user.service';
98

109
@NgModule({
11-
imports: [ CommonModule, HttpModule ],
10+
imports: [],
1211
declarations: [],
1312
exports: [],
1413
providers: [
@@ -26,7 +25,7 @@ export class ApiModule {
2625

2726
constructor( @Optional() @SkipSelf() parentModule: ApiModule) {
2827
if (parentModule) {
29-
throw new Error('ApiModule is already loaded. Import your base AppModule only.');
28+
throw new Error('ApiModule is already loaded. Import in your base AppModule only.');
3029
}
3130
}
3231
}

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
2.3.0
1+
2.3.1-SNAPSHOT

0 commit comments

Comments
 (0)