Angular Integration with API — the Correct Approach

Connecting two worlds — client and back-end app

1. Let’s imagine — a back-end (BE) developer makes a change in API and does not tell the front-end (FE) developer => the app crashes.
2. You are starting a new app — the BE developer makes few endpoints quickly and now we must connect them to our Angular app. Writing API services is so sloooow and painful.

Good news! There is a solution for both of these problems.

Quick version — use:

• Swagger
• swagger-angular-generator

What is Swagger?

Swagger is a way how to document an API. It specifies the request and response objects for given URL.

Every major BE framework has a dedicated library that is capable of auto-generating such documentation, e.g. if using Python’s Django framework, you can use drf-yasg.

The outputted file format can be json or yaml.

Example swagger.json can look like this:

{
  "swagger": "2.0",
  ...
  "paths": {
    "/product/get-product-list/": {
      "post": {
        "operationId": "product_get-product-list_create",
        "description": "register user",
        "parameters": [
          {
            "name": "data",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/ProductRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/ProductResponse"
              }
            }
          }
        },
        "tags": [
          "product"
        ]
      },
      "parameters": []
    },
    ...
  },
  "definitions": {
    "ProductRequest": {
      "required": [
        "price"
      ],
      "type": "object",
      "properties": {
        "price": {
          "title": "Price",
          "type": "string",
          "format": "decimal"
        }
      }
    },
    "ProductResponse": {
      "required": [
        ...
      ],
      "type": "object",
      "properties": {...}
    }
  }
}

What is swagger-angular-generator?

An Angular library that takes the swagger definition (generated by the back-end) and generates Angular code that connects the FE app to the API.

How does the generated files look like?

Have a look at the test project within the library. See directories controllers (these are the API services) and defs (these are the TypeScript interfaces)

Step by step

1. Generate the swagger.json file from back-end

• Let assume we are using Django on back-end with drf-yasg installed and swagger definition being available on http://localhost:8000/swagger.json
• Now, move to the Angular app and add the following two lines to your package.json

"swagger": "wget -O src/generated/swagger.json 'http://localhost:8000/swagger.json'",
"generate": "swagger-angular-generator -s src/generated/swagger.json -d src/generated"

“swagger” — it downloads the swagger.json definition and saves it to Angular’s project directory

“generate” — command for generating the Angular code based on previously saved swagger.json definition

• Now run npm run swagger — the swagger.json definition has been generated

2. Look if there are any API changes

Look at the generated swagger.json and format/prettify it (in IntelliJ IDEs with Ctrl+Alt+L) so that instead of single line,

you see a structured json data.

Someone just renamed price to product_price!!!

If using Git, this makes it possible to see API changes since the last swagger.json was generated.

3. Generate Angular code

Now when you discovered there has been changes to the API, we should generate the new Angular code with npm run generate.

4. Connect your app to the Angular’s generated API services

Now you have the API services and associated TypeScript interfaces generated. Use them.

All the generated goodies at one place

The API services are in controllers directory, the interfaces in the defs directory.

5. Take a break, you just saved yourself so much time!!!

We have used the generator on several large projects, each with tens of endpoints. I seriously cannot imagine we would write the same code in hand.

Is there anything else I should know?

Yes, the swagger-angular-generator can do even more.

It can generate form services for POST, PUT and PATCH endpoints. Hence, it will save you time while creating forms for such endpoints.

If you are using Angular’s ngrx for state management, you can:

• Call the endpoints by dispatching generated actions.
• Retrieve the data by subscribing to store under generated tags.