@revxui/api-clients-ts 3.0.0-beta02-01 → 3.0.0-beta02-03

package/README.md

@@ -1,180 +1,185 @@
-## @revxui/api-clients-ts@3.0.0-beta02-01
+# @revxui/api-clients-ts@3.0.0-beta02-03
 
-### Building
+No description provided (generated by Openapi Generator https://github.com/openapitools/openapi-generator)
+
+The version of the OpenAPI document: v0
+
+## Building
 
 To install the required dependencies and to build the typescript sources run:
-```
+
+```console
 npm install
 npm run build
 ```
 
-### publishing
+## Publishing
 
-First build the package than run ```npm publish dist``` (don't forget to specify the `dist` folder!)
+First build the package then run `npm publish dist` (don't forget to specify the `dist` folder!)
 
-### consuming
+## Consuming
 
 Navigate to the folder of your consuming project and run one of next commands.
 
 _published:_
 
-```
-npm install @revxui/api-clients-ts@3.0.0-beta02-01 --save
+```console
+npm install @revxui/api-clients-ts@3.0.0-beta02-03 --save
 ```
 
 _without publishing (not recommended):_
 
-```
+```console
 npm install PATH_TO_GENERATED_PACKAGE/dist.tgz --save
 ```
 
-It's important to take the tgz file, otherwise you'll get trouble with links on windows.  
+_It's important to take the tgz file, otherwise you'll get trouble with links on windows_
 
 _using `npm link`:_
 
 In PATH_TO_GENERATED_PACKAGE/dist:
-```
+
+```console
 npm link
 ```
 
 In your project:
-```
+
+```console
 npm link @revxui/api-clients-ts
 ```
 
 __Note for Windows users:__ The Angular CLI has troubles to use linked npm packages.
-Please refer to this issue https://github.com/angular/angular-cli/issues/8284 for a solution / workaround.
+Please refer to this issue <https://github.com/angular/angular-cli/issues/8284> for a solution / workaround.
 Published packages are not effected by this issue.
 
-
-#### General usage
+### General usage
 
 In your Angular project:
 
+```typescript
 
-```
-// without configuring providers
-import { ApiModule } from '@revxui/api-clients-ts';
-import { HttpClientModule } from '@angular/common/http';
-
+import { ApplicationConfig } from '@angular/core';
+import { provideHttpClient } from '@angular/common/http';
+import { provideApi } from '@revxui/api-clients-ts';
 
-@NgModule({
-    imports: [
-        ApiModule,
-        // make sure to import the HttpClientModule in the AppModule only,
-        // see https://github.com/angular/angular/issues/20575
-        HttpClientModule
+export const appConfig: ApplicationConfig = {
+    providers: [
+        // ...
+        provideHttpClient(),
+        provideApi()
     ],
-    declarations: [ AppComponent ],
-    providers: [],
-    bootstrap: [ AppComponent ]
-})
-export class AppModule {}
+};
 ```
 
+**NOTE**
+If you're still using `AppModule` and haven't [migrated](https://angular.dev/reference/migrations/standalone) yet, you can still import an Angular module:
+```typescript
+import { ApiModule } from '@revxui/api-clients-ts';
 ```
-// configuring providers
-import { ApiModule, Configuration, ConfigurationParameters } from '@revxui/api-clients-ts';
-
-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 {}
+
+If different from the generated base path, during app bootstrap, you can provide the base path to your service.
+
+```typescript
+import { ApplicationConfig } from '@angular/core';
+import { provideHttpClient } from '@angular/common/http';
+import { provideApi } from '@revxui/api-clients-ts';
+
+export const appConfig: ApplicationConfig = {
+    providers: [
+        // ...
+        provideHttpClient(),
+        provideApi('http://localhost:9999')
+    ],
+};
 ```
 
+```typescript
+// with a custom configuration
+import { ApplicationConfig } from '@angular/core';
+import { provideHttpClient } from '@angular/common/http';
+import { provideApi } from '@revxui/api-clients-ts';
+
+export const appConfig: ApplicationConfig = {
+    providers: [
+        // ...
+        provideHttpClient(),
+        provideApi({
+            withCredentials: true,
+            username: 'user',
+            password: 'password'
+        })
+    ],
+};
 ```
-import { DefaultApi } from '@revxui/api-clients-ts';
 
-export class AppComponent {
-	 constructor(private apiGateway: DefaultApi) { }
-}
+```typescript
+// with factory building a custom configuration
+import { ApplicationConfig } from '@angular/core';
+import { provideHttpClient } from '@angular/common/http';
+import { provideApi, Configuration } from '@revxui/api-clients-ts';
+
+export const appConfig: ApplicationConfig = {
+    providers: [
+        // ...
+        provideHttpClient(),
+        {
+            provide: Configuration,
+            useFactory: (authService: AuthService) => new Configuration({
+                    basePath: 'http://localhost:9999',
+                    withCredentials: true,
+                    username: authService.getUsername(),
+                    password: authService.getPassword(),
+            }),
+            deps: [AuthService],
+            multi: false
+        }
+    ],
+};
 ```
 
-Note: The ApiModule is restricted to being instantiated once app wide.
-This is to ensure that all services are treated as singletons.
+### Using multiple OpenAPI files / APIs
 
-#### Using multiple swagger files / APIs / ApiModules
-In order to use multiple `ApiModules` generated from different swagger files,
+In order to use multiple APIs generated from different OpenAPI 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 {
+```typescript
+import { provideApi as provideUserApi } from 'my-user-api-path';
+import { provideApi as provideAdminApi } from 'my-admin-api-path';
+import { HttpClientModule } from '@angular/common/http';
+import { environment } from '../environments/environment';
 
-}
+export const appConfig: ApplicationConfig = {
+    providers: [
+        // ...
+        provideHttpClient(),
+        provideUserApi(environment.basePath),
+        provideAdminApi(environment.basePath),
+    ],
+};
 ```
 
+### Customizing path parameter encoding
 
-### Set service base path
-If different than the generated base path, during app bootstrap, you can provide the base path to your service. 
+Without further customization, only [path-parameters][parameter-locations-url] of [style][style-values-url] 'simple'
+and Dates for format 'date-time' are encoded correctly.
 
-```
-import { BASE_PATH } from '@revxui/api-clients-ts';
+Other styles (e.g. "matrix") are not that easy to encode
+and thus are best delegated to other libraries (e.g.: [@honoluluhenk/http-param-expander]).
 
-bootstrap(AppComponent, [
-    { provide: BASE_PATH, useValue: 'https://your-web-service.com' },
-]);
-```
-or
+To implement your own parameter encoding (or call another library),
+pass an arrow-function or method-reference to the `encodeParam` property of the Configuration-object
+(see [General Usage](#general-usage) above).
 
-```
-import { BASE_PATH } from '@revxui/api-clients-ts';
+Example value for use in your Configuration-Provider:
 
-@NgModule({
-    imports: [],
-    declarations: [ AppComponent ],
-    providers: [ provide: BASE_PATH, useValue: 'https://your-web-service.com' ],
-    bootstrap: [ AppComponent ]
+```typescript
+new Configuration({
+    encodeParam: (param: Param) => myFancyParamEncoder(param),
 })
-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 '@revxui/api-clients-ts';
-import { environment } from '../environments/environment';
 
-@NgModule({
-  declarations: [
-    AppComponent
-  ],
-  imports: [ ],
-  providers: [{ provide: BASE_PATH, useValue: environment.API_BASE_PATH }],
-  bootstrap: [ AppComponent ]
-})
-export class AppModule { }
-```  
+[parameter-locations-url]: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameter-locations
+[style-values-url]: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#style-values
+[@honoluluhenk/http-param-expander]: https://www.npmjs.com/package/@honoluluhenk/http-param-expander