modesta

Simplest zero-dependency Swagger/OpenAPI --> TypeScript proxy generator

What Is This?

When accessing an API provided via Swagger from TypeScript, it’s only natural to want to automatically generate TypeScript type definitions to ensure type-safe API access. There are several "transformation tools" available to meet this need, and modesta is one of them.

So, what sets modesta apart?

• It has almost no environment dependencies and is very easy to use.
• It’s easy to extend to support custom transports.
• The transformation process can be almost fully automated using a Vite plugin.
• It has no unnecessary dependencies on external libraries.

For example, given a Swagger file like this (YAML is also supported):

{
  "openapi": "3.0.3",
  "info": {
    "title": "User API",
    "version": "1.0.0"
  },
  "paths": {
    "/users/{id}": {
      "get": {
        "operationId": "GetUser",
        "summary": "Get a user.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "required": ["id", "name"],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          }
        }
      }
    }
  }
}

and running the following command:

modesta swagger.json src/generated/modesta_proxy.ts

you get a proxy file (TypeScript code) like this (partially omitted and simplified):

// This file is auto-generated by modesta.
// Do not edit manually

export interface AccessorSenderInterface { /* ... */ }
export interface CreateFetchSenderOptions { /* ... */ }

export const createFetchSender = (
  options?: CreateFetchSenderOptions | undefined
): AccessorSenderInterface => {
  /* ... (helper implementation is generated here) */
};

export interface User {
  id: string;
  name: string;
}

export interface GetUser_get_arguments {
  id: string;
}

export interface GetUser {
  get: (
    args: GetUser_get_arguments,
    options?: AccessorOptions | undefined
  ) => Promise<User>;
}

export function create_GetUser_accessor(
  sender: AccessorSenderInterface
): GetUser;
/* ... (additional overloads are generated here) */

As you can see, the generated proxy file remains self-contained and adds no external runtime dependency. Using it, you can easily write API calling code like this:

import {
  create_GetUser_accessor,
  createFetchSender,
} from './generated/userApi';

// Prepare a Sender
const sender = createFetchSender();

//  :
//  :

// Access the API (typed)
const userApi = create_GetUser_accessor(sender);
const user = await userApi.get({ id: '42' });

console.log(user.name);

You can either perform this process manually or automate it using a Vite plugin.

Main Features

• Reads Swagger files (JSON/YAML) and generates TypeScript source code.
• Concise output and a clear interface minimize obstacles when integrating the code into applications.
• Zero runtime dependencies; completely standalone code output. Usable in any environment, including browsers and Node.js.
• Usable both as a CLI and as a library API. Additionally, it can be integrated with HMR using the Vite plugin.
• Tested with Swashbuckle.AspNetCore and Huma swagger/OpenAPI output.

Installation

Add it to your devDependencies:

npm install -D modesta

Or, you can install CLI command modesta globally:

npm install -g modesta

Or, you can run it directly with npx:

npx modesta swagger.json src/generated/modesta_proxy.ts

Usage

CLI

Run the CLI like this:

modesta
modesta swagger.json
modesta swagger.json src/generated/modesta_proxy.ts
modesta https://example.com/swagger/v1/swagger.json src/generated/modesta_proxy.ts
modesta --sync

• If the first positional argument is omitted, it reads the Swagger file from stdin.
• If the first positional argument is present, it reads that file. When the argument is an http/https URL, it fetches the file directly from that site.
  • If --insecure is specified, TLS certificate verification is disabled for remote https inputs.
• If the second positional argument is omitted, it writes the generated proxy file (TypeScript source code) to stdout.
• If the second positional argument is present, it writes the proxy file to that path.
• If --sync is specified on its own, it reads and executes the Vite plugin configuration (see the next section).

Vite Plugin

By using the Vite plugin, you can integrate it into Vite's build lifecycle. A particular advantage is that HMR is automatically applied when the Swagger file is updated:

import { defineConfig } from 'vite';
import modesta from 'modesta/vite';

export default defineConfig({
  plugins: [
    // Add the modesta Vite plugin
    modesta({
      // When this Swagger file is updated, the proxy file is updated too
      source: './swagger.json',
    }),
  ],
});

The options are:

• source is required and specifies the location of the Swagger file. You can specify a local file path, a file URL, or an http/https URL.
• insecure disables TLS certificate verification for remote https URLs. It defaults to false.
• outputPath is the output path for the proxy file. If omitted, src/generated/modesta_proxy.ts is used.
• If the input file is located on the local file system, the proxy file is generated when the Vite plugin starts, and subsequent changes are monitored and updated.
• If the input file is a URL, the plugin does not automatically update it. Instead, use modesta --sync to synchronize explicitly.

When the input file is a URL that points to a remote host, the plugin cannot watch it for changes. In that case, you can manually update the proxy file with the modesta --sync command.

For example, configure the Vite plugin to reference a remote Swagger file:

export default defineConfig({
  plugins: [
    modesta({
      // Reference Swagger published from a remote host
      source: 'https://example.com/api/v2/swagger.json',
    }),
  ],
});

and add a scripts entry like this to package.json:

{
  "scripts": {
    "dev": "vite dev",
    "sync": "modesta --sync"
  }
}

Then npm run sync can update the proxy file and keep the update process simple.

Documentation

More information, see the repository documentation.

Discussions and Pull Requests

For discussions, please refer to the GitHub Discussions page.

Pull requests are welcome! Please submit them as diffs against the develop branch and squashed changes before send.

License

Under MIT.