swaxios

Swaxios

A Swagger (OpenAPI v2) API client generator based on axios and written in TypeScript.

Motivation

The Swaxios project automates the creation of an API client for TypeScript applications, which can be used in web browsers and Node.js environments.

At the time of writing this tool (2019-04-26), the Swagger Codegen project only provided separate SDK generators for browsers and Node.js (typescript-fetch and typescript-node). Unfortunately, the typescript-fetch generator for browsers is not compatible with all Node.js applications since the fetch API became globally available only as an experimental feature in Node.js 18 (2022-04-19).

Swaxios offers an API generator that works in both environments (browsers & Node.js 16+) by utilizing the flexible axios request library. API calls are routed through axios and can be easily customized using request interceptors.

Limitations

This library can only work with a valid OpenAPI Version 2 specification, which must be in the form of a file or URL. It does not support OpenAPI Version 3 specifications.

If you need a generator for Open API v3 specs, you can test typescript-axios from Swagger Codegen (added on 2020-09-21).

java -jar swagger-codegen-cli-3.0.24.jar generate -l typescript-axios -i ./swagger.json -o ./api-client

• Download Swagger Codegen 3.0.24 (Release Notes)

There is also an npm package (@openapitools/openapi-generator-cli) which exposes this generator. You can use it the following way in your scripts:

{
  "scripts": {
    "generate": "openapi-generator-cli generate -i ./swagger.json -g typescript-axios -p \"withoutRuntimeChecks=true,withInterfaces=true\" -o ./api-client"
  }
}

Installation

You can install Swaxios globally (npm i -g swaxios) or add it to your devDependencies.

Usage

Display all CLI options:

swaxios --help

If you pass an OpenAPI v2 specification (JSON or YAML) to Swaxios, then it generates a fully typed API client for you which uses axios under the hood:

# Provide a Swagger input file (JSON or YAML)
swaxios -i ./path/to/swagger.json -o ./path/to/output/directory
swaxios -i ./path/to/swagger.yml -o ./path/to/output/directory

# Alternative: Provide a URL to a Swagger endpoint
swaxios -i http://127.0.0.1:3000/documentation-json -o ./path/to/output/directory

With the -f option, you can force Swaxios to overwrite existing files in the output path:

swaxios -i ./path/to/swagger.json -o ./path/to/output/directory -f

Examples

You can find many examples of generated API client code in our snapshots section.

Here is a basic example:

ExchangeService.ts

/* tslint:disable */

/**
 * This file was automatically generated by "Swaxios".
 * It should not be modified by hand.
 */

import {AxiosInstance, AxiosRequestConfig} from 'axios';

export class ExchangeService {
  private readonly apiClient: AxiosInstance;

  constructor(apiClient: AxiosInstance) {
    this.apiClient = apiClient;
  }

  deleteExchange = async (id: number): Promise<void> => {
    const config: AxiosRequestConfig = {
      method: 'delete',
      url: `/api/v1/exchange/${id}`,
    };
    await this.apiClient.request(config);
  };
}

It has been generated from the following path:

swagger.json

{
  // ...
  "paths": {
    "/api/v1/exchange/{id}": {
      "delete": {
        "consumes": ["application/json"],
        "operationId": "deleteExchange",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "type": "number"
          }
        ],
        "produces": ["application/json"],
        "responses": {
          "200": {
            "description": ""
          }
        }
      }
    }
  }
  // ...
}

Changelog

0.2.5 (2024-05-11)

New Features

• Upgrade Commander (#536) (578c26a0)
• Upgrade to Node v20 (#535) (69a6b3e5)
• Automatically merge dependency updates (6896208a)