Skip to content

Commit 7391063

Browse files
jase88jase88
committed
feat(angular): add support for README_beforeV17 and update provideApi return type
1 parent 5336b5e commit 7391063

3 files changed

Lines changed: 247 additions & 3 deletions

File tree

‎modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/TypeScriptAngularClientCodegen.java‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -204,7 +204,14 @@ public void processOpts() {
204204
supportingFiles.add(new SupportingFile("param.mustache", getIndexDirectory(), "param.ts"));
205205
supportingFiles.add(new SupportingFile("gitignore", "", ".gitignore"));
206206
supportingFiles.add(new SupportingFile("git_push.sh.mustache", "", "git_push.sh"));
207-
supportingFiles.add(new SupportingFile("README.mustache", getIndexDirectory(), "README.md"));
207+
208+
if(ngVersionAtLeast_17) {
209+
supportingFiles.add(new SupportingFile("README.mustache", getIndexDirectory(), "README.md"));
210+
}
211+
else {
212+
supportingFiles.add(new SupportingFile("README_beforeV17.mustache", getIndexDirectory(), "README.md"));
213+
}
214+
208215

209216
if (!ngVersion.atLeast("9.0.0")) {
210217
throw new IllegalArgumentException("Invalid ngVersion: " + ngVersion + ". Only Angular v9+ is supported.");

‎modules/openapi-generator/src/main/resources/typescript-angular/README_beforeV17.mustache‎

Lines changed: 236 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,236 @@
1+
# {{npmName}}@{{npmVersion}}
2+
3+
{{{appDescription}}}
4+
5+
{{#version}}The version of the OpenAPI document: {{{.}}}{{/version}}
6+
7+
## Building
8+
9+
To install the required dependencies and to build the typescript sources run:
10+
11+
```console
12+
npm install
13+
npm run build
14+
```
15+
16+
## Publishing
17+
18+
First build the package then run `npm publish dist` (don't forget to specify the `dist` folder!)
19+
20+
## Consuming
21+
22+
Navigate to the folder of your consuming project and run one of next commands.
23+
24+
_published:_
25+
26+
```console
27+
npm install {{npmName}}@{{npmVersion}} --save
28+
```
29+
30+
_without publishing (not recommended):_
31+
32+
```console
33+
npm install PATH_TO_GENERATED_PACKAGE/dist.tgz --save
34+
```
35+
36+
_It's important to take the tgz file, otherwise you'll get trouble with links on windows_
37+
38+
_using `npm link`:_
39+
40+
In PATH_TO_GENERATED_PACKAGE/dist:
41+
42+
```console
43+
npm link
44+
```
45+
46+
In your project:
47+
48+
```console
49+
npm link {{npmName}}
50+
```
51+
52+
__Note for Windows users:__ The Angular CLI has troubles to use linked npm packages.
53+
Please refer to this issue <https://github.com/angular/angular-cli/issues/8284> for a solution / workaround.
54+
Published packages are not effected by this issue.
55+
56+
### General usage
57+
58+
In your Angular project:
59+
60+
```typescript
61+
// without configuring providers
62+
import { {{apiModuleClassName}} } from '{{npmName}}';
63+
import { HttpClientModule } from '@angular/common/http';
64+
65+
@NgModule({
66+
imports: [
67+
{{apiModuleClassName}},
68+
// make sure to import the HttpClientModule in the AppModule only,
69+
// see https://github.com/angular/angular/issues/20575
70+
HttpClientModule
71+
],
72+
declarations: [ AppComponent ],
73+
providers: [],
74+
bootstrap: [ AppComponent ]
75+
})
76+
export class AppModule {}
77+
```
78+
79+
```typescript
80+
// configuring providers
81+
import { {{apiModuleClassName}}, {{configurationClassName}}, {{configurationParametersInterfaceName}} } from '{{npmName}}';
82+
83+
export function apiConfigFactory (): {{configurationClassName}} {
84+
const params: {{configurationParametersInterfaceName}} = {
85+
// set configuration parameters here.
86+
}
87+
return new {{configurationClassName}}(params);
88+
}
89+
90+
@NgModule({
91+
imports: [ {{apiModuleClassName}}.forRoot(apiConfigFactory) ],
92+
declarations: [ AppComponent ],
93+
providers: [],
94+
bootstrap: [ AppComponent ]
95+
})
96+
export class AppModule {}
97+
```
98+
99+
```typescript
100+
// configuring providers with an authentication service that manages your access tokens
101+
import { {{apiModuleClassName}}, {{configurationClassName}} } from '{{npmName}}';
102+
103+
@NgModule({
104+
imports: [ {{apiModuleClassName}} ],
105+
declarations: [ AppComponent ],
106+
providers: [
107+
{
108+
provide: {{configurationClassName}},
109+
useFactory: (authService: AuthService) => new {{configurationClassName}}(
110+
{
111+
basePath: environment.apiUrl,
112+
accessToken: authService.getAccessToken.bind(authService)
113+
}
114+
),
115+
deps: [AuthService],
116+
multi: false
117+
}
118+
],
119+
bootstrap: [ AppComponent ]
120+
})
121+
export class AppModule {}
122+
```
123+
124+
```typescript
125+
import { DefaultApi } from '{{npmName}}';
126+
127+
export class AppComponent {
128+
constructor(private apiGateway: DefaultApi) { }
129+
}
130+
```
131+
132+
Note: The {{apiModuleClassName}} is restricted to being instantiated once app wide.
133+
This is to ensure that all services are treated as singletons.
134+
135+
### Using multiple OpenAPI files / APIs / {{apiModuleClassName}}s
136+
137+
In order to use multiple `{{apiModuleClassName}}s` generated from different OpenAPI files,
138+
you can create an alias name when importing the modules
139+
in order to avoid naming conflicts:
140+
141+
```typescript
142+
import { {{apiModuleClassName}} } from 'my-api-path';
143+
import { {{apiModuleClassName}} as OtherApiModule } from 'my-other-api-path';
144+
import { HttpClientModule } from '@angular/common/http';
145+
146+
@NgModule({
147+
imports: [
148+
{{apiModuleClassName}},
149+
OtherApiModule,
150+
// make sure to import the HttpClientModule in the AppModule only,
151+
// see https://github.com/angular/angular/issues/20575
152+
HttpClientModule
153+
]
154+
})
155+
export class AppModule {
156+
157+
}
158+
```
159+
160+
### Set service base path
161+
162+
If different than the generated base path, during app bootstrap, you can provide the base path to your service.
163+
164+
```typescript
165+
import { BASE_PATH } from '{{npmName}}';
166+
167+
bootstrap(AppComponent, [
168+
{ provide: BASE_PATH, useValue: 'https://your-web-service.com' },
169+
]);
170+
```
171+
172+
or
173+
174+
```typescript
175+
import { BASE_PATH } from '{{npmName}}';
176+
177+
@NgModule({
178+
imports: [],
179+
declarations: [ AppComponent ],
180+
providers: [ provide: BASE_PATH, useValue: 'https://your-web-service.com' ],
181+
bootstrap: [ AppComponent ]
182+
})
183+
export class AppModule {}
184+
```
185+
186+
### Using @angular/cli
187+
188+
First extend your `src/environments/*.ts` files by adding the corresponding base path:
189+
190+
```typescript
191+
export const environment = {
192+
production: false,
193+
API_BASE_PATH: 'http://127.0.0.1:8080'
194+
};
195+
```
196+
197+
In the src/app/app.module.ts:
198+
199+
```typescript
200+
import { BASE_PATH } from '{{npmName}}';
201+
import { environment } from '../environments/environment';
202+
203+
@NgModule({
204+
declarations: [
205+
AppComponent
206+
],
207+
imports: [ ],
208+
providers: [{ provide: BASE_PATH, useValue: environment.API_BASE_PATH }],
209+
bootstrap: [ AppComponent ]
210+
})
211+
export class AppModule { }
212+
```
213+
214+
### Customizing path parameter encoding
215+
216+
Without further customization, only [path-parameters][parameter-locations-url] of [style][style-values-url] 'simple'
217+
and Dates for format 'date-time' are encoded correctly.
218+
219+
Other styles (e.g. "matrix") are not that easy to encode
220+
and thus are best delegated to other libraries (e.g.: [@honoluluhenk/http-param-expander]).
221+
222+
To implement your own parameter encoding (or call another library),
223+
pass an arrow-function or method-reference to the `encodeParam` property of the Configuration-object
224+
(see [General Usage](#general-usage) above).
225+
226+
Example value for use in your Configuration-Provider:
227+
228+
```typescript
229+
new Configuration({
230+
encodeParam: (param: Param) => myFancyParamEncoder(param),
231+
})
232+
```
233+
234+
[parameter-locations-url]: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameter-locations
235+
[style-values-url]: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#style-values
236+
[@honoluluhenk/http-param-expander]: https://www.npmjs.com/package/@honoluluhenk/http-param-expander

‎modules/openapi-generator/src/main/resources/typescript-angular/provide-api.mustache‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
1-
import { makeEnvironmentProviders } from "@angular/core";
1+
import { EnvironmentProviders, makeEnvironmentProviders } from "@angular/core";
22
import { {{configurationClassName}}, {{configurationParametersInterfaceName}} } from './configuration';
33
import { BASE_PATH } from './variables';
44

5-
export function provideApi(configOrBasePath: string | {{configurationParametersInterfaceName}}) {
5+
// Returns the service class providers, to be used in the [ApplicationConfig](https://angular.dev/api/core/ApplicationConfig).
6+
export function provideApi(configOrBasePath: string | {{configurationParametersInterfaceName}}): EnvironmentProviders {
67
return makeEnvironmentProviders([
78
typeof configOrBasePath === "string"
89
? { provide: BASE_PATH, useValue: configOrBasePath }

0 commit comments

Comments
 (0)