Swaggie

Generate ES6 or Typescript code from an OpenAPI 3.0 spec, so that accessing REST API resources from the client code is less error-prone, static-typed and just easier to use long-term.

You can take a look at the Examples section down below.

Project is based and inspired by OpenApi Client.

Install

In your project

npm install swaggie --save-dev

Or globally to run CLI from anywhere

npm install swaggie -g

OpenAPI versions

Swaggie from version 1.0 supports OpenAPI 3.0 (and some features of 3.1). Swagger or OpenAPI v2 documents are not supported anymore, but you have few options how to deal with it:

• (preferred) From your backend server generate OpenAPI 3.0 spec instead of version 2 (samples are updated to use OpenAPI 3.0)
• Convert your OpenAPI 2.0 spec to 3.0 using swagger2openapi tool (or something similar)
• If you can't do that for any reason, you can stick to Swaggie v0.x. But upgrade is suggested

Please note that OpenAPI 3.0 is a major spec upgrade and it's possible that there will be some breaking changes in the generated code. I have tried my best to minimize the impact, but it was not possible to avoid it completely.

More info about breaking changes can be found in the Releases.

CLI

Usage: swaggie [options]

Options:

  -V, --version             output the version number
  -c, --config <path>       The path to the configuration JSON file. You can do all the set up there instead of parameters in the CLI
  -s, --src <url|path>      The url or path to the Open API spec file
  -o, --out <filePath>      The path to the file where the API would be generated. Use stdout if left empty
  -b, --baseUrl <string>    Base URL that will be used as a default value in the clients (default: "")
  -t, --template <string>   Template used forgenerating API client. Default: "axios"
  --preferAny               Use "any" type instead of "unknown" (default: false)
  --servicePrefix <string>  Prefix for service names. Useful when you have multiple APIs and you want to avoid name collisions (default: "")
  --allowDots <bool>        Determines if dots should be used for serialization object properties
  --arrayFormat <format>    Determines how arrays should be serialized (choices: "indices", "repeat", "brackets")
  -h, --help                display help for command

Sample CLI usage using Swagger's Pet Store:

swaggie -s https://petstore3.swagger.io/api/v3/openapi.json -o ./client/petstore/

swaggie outputs TypeScript that is somehow formatted, but it's far from perfect. You can adjust the generated code by prettifying output using your preferred beautify tool using your repo's styling guidelines. For example involving prettier looks like this:

swaggie -s $URL -o ./client/petstore.ts && prettier ./client/petstore.ts --write`

And this can be easily automated (in the npm scripts for example)

Configuration File

Instead of providing all required flags from the command line you can alternatively create a new JSON file where you can fill up all settings.

Sample configuration looks like this:

{
  "$schema": "https://raw.githubusercontent.com/yhnavein/swaggie/master/schema.json",
  "out": "./src/client/petstore.ts",
  "src": "https://petstore3.swagger.io/api/v3/openapi.json",
  "template": "axios",
  "baseUrl": "/api",
  "preferAny": true,
  "servicePrefix": "",
  "dateFormat": "Date", // "string" | "Date"
  "queryParamsSerialization": {
    "arrayFormat": "repeat", // "repeat" | "brackets" | "indices"
    "allowDots": true
  }
}

Templates

The following templates are bundled with Swaggie:

axios     Default template. Recommended for React / Vue / similar frameworks. Uses axios
xior      Lightweight and modern alternative to axios. Uses [xior](https://github.com/suhaotian/xior#intro)
swr-axios Template that embraces SRW for GET requests and as a fallback uses axios.
fetch     Template similar to axios, but with fetch API instead. Recommended for React / Vue / similar frameworks
ng1       Template for Angular 1 (this is for the old one)
ng2       Template for Angular 2+ (uses HttpClient, InjectionTokens, etc)

If you want to use your own template, you can use the path to your template for the -t parameter:

swaggie -s https://petstore3.swagger.io/api/v3/openapi.json -o ./client/petstore --template ./my-swaggie-template/

Usage – Integrating into your project

Let's assume that you have a PetStore API as your REST API and you are developing a client app written in TypeScript that will consume this API.

Instead of writing any code by hand for fetching particular resources, we will let Swaggie do it for us.

Query Parameters Serialization

When it comes to use of query parameters then you might need to adjust the way these parameters will be serialized, as backend server you are using expects them to be in a specific format. Thankfully in Swaggie you can specify how they should be handled. If you won't provide any configuration, then Swaggie will use the defaults values expected in the ASP.NET Core world.

For your convenience there are few config examples to achieve different serialization formats for an object { "a": { "b": 1 }, "c": [2, 3] }:

Expected Format	allowDots	arrayFormat
?a.b=1&c=2&c=3	true	repeat
?a.b=1&c[]=2&c[]=3	true	brackets
?a.b=1&c[0]=2&c[1]=3	true	indices
?a[b]=1&c=2&c=3	false	repeat
?a[b]=1&c[]=2&c[]=3	false	brackets
?a[b]=1&c[0]=2&c[1]=3	false	indices

Once you know what your backend expects, you can adjust the configuration file accordingly: (below are default values)

{
  "queryParamsSerialization": {
    "arrayFormat": "repeat",
    "allowDots": true
  }
}

Code Quality

Please note that it's recommended to pipe Swaggie command to some prettifier like prettier, biome or dprint to make the generated code look not only nice, but also persistent. Because Swaggie relies on a templating engine, whitespaces are generally a mess, so they may change between versions.

Suggested prettiers

prettier - the most popular one

prettier ./FILE_PATH.ts --write

biome - the super fast one

biome check ./FILE_PATH.ts --apply-unsafe

You are not limited to any of these, but in our examples we will use Prettier. Please remember that these tools needs to be installed first and they need a config file in your project.

Example

Let's run swaggie against PetStore API and see what will happen:

swaggie -s https://petstore3.swagger.io/api/v3/openapi.json -o ./api/petstore.ts && prettier ./api/petstore.ts --write

// ./api/petstore.ts

import Axios, { AxiosPromise } from 'axios';
const axios = Axios.create({
  baseURL: '/api',
  paramsSerializer: (params) =>
    encodeParams(params, null, {
      allowDots: true,
      arrayFormat: 'repeat',
    }),
});

/** [...] **/

export const petClient = {
  /**
   * @param petId
   */
  getPetById(petId: number): AxiosPromise<Pet> {
    let url = `/pet/${encodeURIComponent(`${petId}`)}`;

    return axios.request<Pet>({
      url: url,
      method: 'GET',
    });
  },

  // ... and other methods ...
};

When we have that we can write some domain code and use this auto-generated classes:

// app.ts

import { petClient } from './api/petClient';

petClient.getPetById(123).then((pet) => console.log('Pet: ', pet));

If Petstore owners decide to remove method we use, then after running swaggie again it will no longer be present in the petClient class. This will result in the build error, which is very much appreciated at this stage.

Without this approach, the error would be spotted by our end-user and he/she would not appreciate it at all!

Server config

You might wonder how to set up server to fully utilize Swaggie's features. For that I've added a samples/ folder with sample configurations.

ASP.NET Core + Nswag

ASP.NET Core + Swashbuckle

Server is not necessary to use Swaggie. Swaggie cares only about the JSON/yaml file with the Open API spec, but for your development purpose you might want to have a server that can serve this file automatically from the actual endpoints.

Competitors

If you are familiar with the client-code generators for the Swagger / OpenAPI standards then you might wonder why swaggie is better than existing tools. I compiled a quick comparison with other tools below:

Swaggie

• Fast and small
• Lightweight and easy to start
• Easy to contribute to, custom templates
• Flexible, suits well in the existing apps
• Generates REST clients and all models
• Supports different templates (like axios, fetch, xior, swr-axios, ng1, ng2)
• Written in TypeScript
• Generates only one file with everything you need inside

NSwag

• Slow and big
• Complicated templates, not easy to contribute to
• Enforces usage of other tools and architecture
• Generates more boilerplate code
• Written in .NET, require .NET to execute, although published to npm as well
• Many more features (but mostly for .NET apps), client generation is just a part of it

Hey API

• Fast and small
• No flexibility, other clients are discouraged from use
• Generates a lot of code and multiple files
• Written in TypeScript

Kiota

• A lot of boilerplate code and many files
• Written in .NET, requires .NET to execute, published to NuGet
• Not flexible at all - you need to use their architecture in your code
• Looks like an enterprise solution with many configuration options

Using Swaggie programmatically

const swaggie = require('swaggie');
swaggie
  .genCode({
    src: 'https://petstore3.swagger.io/api/v3/openapi.json',
    out: './api/petstore.ts',
  })
  .then(complete, error);

function complete(spec) {
  console.info('Service generation complete');
}

function error(e) {
  console.error(e.toString());
}

Notes

Supported	Not supported
OpenAPI 3	Swagger 2
allOf, oneOf, anyOf, $ref to schemas	not
Spec formats: JSON, YAML	Very complex query params
Extensions: x-position, x-name, x-enumNames, x-enum-varnames	Multiple response types (one will be used)
Content types: JSON, text, multipart/form-data	Multiple request types (one will be used)
Content types: application/x-www-form-urlencoded, application/octet-stream	References to other spec files
Different types of enum definitions (+ OpenAPI 3.1 support for enums)
Paths inheritance, comments (descriptions)
Getting documents from remote locations or as path reference (local file)
Grouping endpoints by tags + handle gracefully duplicate operation ids