npm package: @progresso/openapi-typescript-client-api-generator
Description: A generator that reads swagger / open api 3 json configs and generates typescript client services with axios
Author: Michael Hilus
Latest version: 1.0.2

# openapi-typescript-client-api-generator
A generator that reads swagger / open api 3 json configs and generates typescript client services with axios.

Hint: implemented with specific use case in mind.

[![npm version](https://badge.fury.io/js/%40progresso%2Fopenapi-typescript-client-api-generator.svg)](https://badge.fury.io/js/%40progresso%2Fopenapi-typescript-client-api-generator)

## Example

Your open-api 3 json config file:
```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "Awesome project API",
    "description": "The API that is just awesome.",
    "version": "1.3.8"
  },
  "tags" : [ { "name" : "users" } ],
  ...
  "paths": {
    "/users": {
      "get": {
        "tags": [ "users" ],
        "operationId": "getAllUsers",
        "description": "Gets all users. Can optionally be filtered by group id.",
        "parameters": [ {
          "name": "groupId",
          "in": "query",
          "description": "The group of the users to retrieve.",
          "required": false,
          "schema": {
            "type": "integer",
            "format": "int32"
          }
        } ],
        "responses": {
          "default": {
            "description": "The users.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref" : "#/components/schemas/User"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/users/{userId}": {
      "get": {
        "tags": [ "users" ],
        "operationId": "getUserById",
        "description": "Retrieve a user by id.",
        "parameters": [ {
          "name": "userId",
          "in": "path",
          "description": "The id of the user to retrieve.",
          "required": true,
          "schema": {
            "type": "integer",
            "format": "int32"
          }
        } ],
        "responses": {
          "default": {
            "description": "The user.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref" : "#/components/schemas/User"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "User": {
        "description": "The user.",
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int32",
            "description": "The id of the user."
          },
          "name": {
            "type": "string",
            "description": "The name of the user."
          },
          "groupId": {
            "type": "integer",
            "format": "int32",
            "description": "The group id of the user."
          }
        }
      }
    }
  }
}
```

Generated model ( `user.ts` )
```typescript
/**
 * Awesome project API 1.3.8 (OpenAPI: 3.0.1)
 * The API that is just awesome.
 *
 * NOTE: This class is auto generated by openapi-typescript-client-api-generator.
 * Do not edit the file manually.
 */

export class User {

    /**
     * Creates a ListColumn.
     *
     * @param {number} id The id of the user.
     * @param {string} name The name of the user.
     * @param {number} groupId The group id of the user.
     */
    constructor(id: number, name: string, groupId: number) {
        this.id = id;
        this.name = name;
        this.groupId = groupId;
    }

    /**
     * The id of the user.
     */
    public id: number;

    /**
     * The name of the user.
     */
    public name: string;

    /**
     * The group id of the user.
     */
    public group id: number;
}
```

Generated service ( `usersService.ts` )
```typescript
/**
 * Awesome project API 1.3.8 (OpenAPI: 3.0.1)
 * The API that is just awesome.
 *
 * NOTE: This class is auto generated by openapi-typescript-client-api-generator.
 * Do not edit the file manually.
 */

import axios from "axios";

import { ServiceBase } from "../../services/serviceBase";
import { IUsersService } from "./usersService.interface";

import { User } from "../models/user";

export class UsersService extends ServiceBase implements IUsersService {
    /**
     * Gets all users. Can optionally be filtered by group id.
     *
     * @param {number} [groupId] The group of the users to retrieve.
     */
    public async getAllUsers(groupId?: number): Promise<User[]> {
        const config = this.getAxiosConfiguration();

        const queryList: string[] = [];
        if (groupId !== undefined) {
            queryList.push(`groupId=${groupId}`);
        }
        const query = `?${queryList.join("&")}`;

        const response = await axios.get<User[]>(`/users${query}`, config);
        return response.data;
    }

    /**
     * Retrieve a user by id..
     *
     * @param {number} userId The id of the user to retrieve.
     */
    public async getUserById(userId?: number): Promise<User[]> {
        const config = this.getAxiosConfiguration();

        const response = await axios.get<User[]>(`/users/${userId}`, config);
        return response.data;
    }
}
```

## Installation
```shell
$ yarn add @progresso/openapi-typescript-client-api-generator --dev
```

## Usage

### Add an open-api 2.0 / 3.x file to your project
Add a swagger (open-api 2.0) or open-api 3 json config file into your project. I.e. at  
`[project-root]/api/awesone-api.json`

### Configure scripts section in package.json
Add a script line into your `package.json`:
```json
{
  ...
  "scripts": {
    "generate": "openapi-typescript-client-api-generator"
  }
}
```
### Implement ServiceBase for request headers
Implement a service base class called `ServiceBase` that implements the following method so you are able to pass custom headers like authentication tokens to your requests: 
```typescript
protected getAxiosConfiguration(): AxiosRequestConfig
```

### Run the generator
Execute the generator with
```shell
$ yarn generate -c /api/awesome-api.json -sb /client/services -s /client/api/services -m /client/api/models -sm /server/modules/api/models
```

## Parameter documentation
All parameters are required currently. All pathes are relative to the project root.

| Parameter    | Description                                                                                               | Example                 |
|--------------|-----------------------------------------------------------------------------------------------------------|-------------------------|
| `-c <path>`  | The path to your json config file.                                                                        | `/api/awesome-api.json` |
| `-sb <path>` | The path to the directory where your `ServiceBase` class is located.                                      | `/client/services`      |
| `-s <path>`  | The path to the directory where the generated services should be saved to. Will be created if neccessary. | `/client/api/services`  |
| `-m <path>`  | The path to the directory where the generated models should be saved to. Will be created if neccessary.   | `/client/api/models`    |
| `-sm <path>` | The path to a directory that contains server side models decorated for `@nestjs/swagger` generation. Used when the config file's version is 2.0 (swagger) to augment services and models by inheritance information. Not used when config file's version is >= 3.0.0 (open-api 3). | `/server/modules/api/models` |