From b7839604484ad9c97a7757d63c5dde98892f8b84 Mon Sep 17 00:00:00 2001 From: Arman Ozak Date: Wed, 23 Sep 2020 16:16:14 +0300 Subject: [PATCH] docs: improve introduction to service proxies --- docs/en/.vscode/settings.json | 13 +++++++++++++ docs/en/UI/Angular/Service-Proxies.md | 27 +++++++++++++-------------- 2 files changed, 26 insertions(+), 14 deletions(-) create mode 100644 docs/en/.vscode/settings.json diff --git a/docs/en/.vscode/settings.json b/docs/en/.vscode/settings.json new file mode 100644 index 0000000000..88052badbc --- /dev/null +++ b/docs/en/.vscode/settings.json @@ -0,0 +1,13 @@ +{ + "grammarly.userWords": [ + "api", + "apiName", + "cli", + "defaultProject", + "formatter", + "md", + "monorepo", + "npx", + "rootNamespace" + ] +} \ No newline at end of file diff --git a/docs/en/UI/Angular/Service-Proxies.md b/docs/en/UI/Angular/Service-Proxies.md index ece959a90d..becec11ed9 100644 --- a/docs/en/UI/Angular/Service-Proxies.md +++ b/docs/en/UI/Angular/Service-Proxies.md @@ -1,16 +1,15 @@ ## Service Proxies -It is common to call a REST endpoint in the server from our Angular applications. In this case, we generally create **services** (those have methods for each service method on the server side) and **model objects** (matches to [DTOs](../../Data-Transfer-Objects) in the server side). +Calling a REST endpoint from Angular applications is common. We usually create **services** matching server-side controllers and **interfaces** matching [DTOs](../../Data-Transfer-Objects) to interact with the server. This often results in manually transforming C# code into TypeScript equivalents and that is unfortunate, if not intolerable. -In addition to manually creating such server-interacting services, we could use tools like [NSWAG](https://github.com/RicoSuter/NSwag) to generate service proxies for us. But NSWAG has the following problems we've experienced: +To avoid manual effort, we might use a tool like [NSWAG](https://github.com/RicoSuter/NSwag) that generates service proxies. However, NSWAG has some disadvantages: -- It generates a **big, single** .ts file which has some problems; - - It get **too large** when your application grows. - - It doesn't fit into the **[modular](../../Module-Development-Basics) approach** of the ABP framework. -- It creates a bit **ugly code**. We want to have a clean code (just like if we write manually). -- It can not generate the same **method signature** declared in the server side (because swagger.json doesn't exactly reflect the method signature of the backend service). We've created an endpoint that exposes server side method contacts to allow clients generate a better aligned client proxies. +- It generates **a single .ts file** which gets **too large** as your application grows. Also, this single file does not fit the **[modular](../../Module-Development-Basics) approach** of ABP. +- To be honest, the generated code is a bit **ugly**. We would like to produce code that looks as if someone wrote it. +- Since swagger.json **does not reflect the exact method signature** of backend services, NSWAG cannot reflect them on the client-side as well. + +ABP introduces an endpoint that exposes server-side method contracts. When the `generate-proxy` command is run, ABP CLI makes an HTTP request to this endpoint and generates better-aligned client proxies in TypeScript. It organizes folders according to namespaces, adds barrel exports, and reflects method signatures in Angular services. -ABP CLI changes that via the `generate-proxy` command. It automatically generates the client proxies in TypeScript. by creating folders which separated by module names in the `src/app` folder. Run the following command in the **root folder** of the angular application: ```bash @@ -19,13 +18,13 @@ abp generate-proxy The command without any parameters creates proxies only for your own application's services and places them in your default Angular application. There are several parameters you may use to modify this behavior. See the [CLI documentation](../../CLI) for details. -The generated files will be placed in a folder called `proxy` at the root of target project. +The generated files will be placed in a folder called `proxy` at the root of the target project. ![generated-files-via-generate-proxy](./images/generated-files-via-generate-proxy.png) Each folder will have models, enums, and services defined at related namespace accompanied by a barrel export, i.e. an `index.ts` file for easier imports. -> The cammand is able to find application/library roots by reading `angular.json` file. Make sure you have either defined your target project as the `defaultProject` or pass the `--target` parameter to the command. This also means that you may have a monorepo workspace. +> The command can find application/library roots by reading the `angular.json` file. Make sure you have either defined your target project as the `defaultProject` or pass the `--target` parameter to the command. This also means that you may have a monorepo workspace. ### Angular Project Configuration @@ -74,9 +73,9 @@ export const environment: Config.Environment = { The `generate-proxy` command generates one service per back-end controller and a method (property with a function value actually) for each action in the controller. These methods call backend APIs via [RestService](./Http-Requests#restservice). -A variable named `apiName` (available as of v2.4) is defined in each service. `apiName` matches the module's RemoteServiceName. This variable passes to the `RestService` as a parameter at each request. If there is no microservice API defined in the environment, `RestService` uses the default. See [getting a specific API endpoint from application config](./Http-Requests#how-to-get-a-specific-api-endpoint-from-application-config) +A variable named `apiName` (available as of v2.4) is defined in each service. `apiName` matches the module's `RemoteServiceName`. This variable passes to the `RestService` as a parameter at each request. If there is no microservice API defined in the environment, `RestService` uses the default. See [getting a specific API endpoint from application config](./Http-Requests#how-to-get-a-specific-api-endpoint-from-application-config) -The `providedIn` property of the services is defined as `'root'`. Therefore there is no need to provide them in a module. You can use them directly by injecting them into constructor as shown below: +The `providedIn` property of the services is defined as `'root'`. Therefore there is no need to provide them in a module. You can use them directly by injecting them into the constructor as shown below: ```js import { BookService } from '@proxy/books'; @@ -114,7 +113,7 @@ export class BookComponent implements OnInit { ### Enums -Enums have always been difficult to populate in the frontend. The `generate-proxy` command genarates enums in a separate file and exports a ready-to-use options constant from the same file. So you can import them as follows: +Enums have always been difficult to populate in the frontend. The `generate-proxy` command generates enums in a separate file and exports a ready-to-use "options constant" from the same file. So you can import them as follows: ```js import { bookGenreOptions } from "@proxy/books"; @@ -132,7 +131,7 @@ export class BookComponent implements OnInit { ```