openapi2aspida

Convert OpenAPI 3.0 or Swagger 2.0 definitions (YAML or JSON) into aspida type-safe API clients.

To use it, you can run the CLI via npx pointing to a remote URL or a local file, then install the necessary dependencies to run the generated client (such as @aspida/axios and axios).

$ mkdir petstore-api
$ cd petstore-api
$ npx openapi2aspida -i https://petstore.swagger.io/v2/swagger.json

$ npm init -y
$ npm install @aspida/axios axios typescript ts-node @types/node

Instead of passing CLI flags every time, you can create an aspida.config.js file in your project root to manage generation settings. Note that the input key in this config refers to the source OpenAPI file, which acts as the output for the generated files.

module.exports = {
  input: 'api', // This is the directory where aspida files will be output
  outputEachDir: true, // Generate $api.ts in each endpoint directory
  openapi: { inputFile: 'https://petstore.swagger.io/v2/swagger.json' },
};

Then run:

$ npx openapi2aspida

Once openapi2aspida has generated the api/$api.ts file, you can use it by passing an aspida-compatible client (like @aspida/axios) to the generated api function. This provides full type safety for request bodies and response types.

import axiosClient from '@aspida/axios';
import api from './api/$api';
import type { Pet } from './api/@types';

(async () => {
  const client = api(axiosClient());
  const petId = 100;
  const body: Pet = {
    id: petId,
    name: 'hoge',
    photoUrls: [],
    status: 'available',
  };

  // POST request with typed body
  await client.pet.$post({ body });

  // GET request with path parameter
  const pet = await client.pet._petId(petId).$get();
  console.log(pet);
})();

Use the following flags to control the generation process via the command line:

• -i, --input: Path to the OpenAPI spec file (URL or local path).
• -o, --outputdir: Change the directory where the generated files are placed.
• -c, --config: Path to an aspida configuration file.
• --version: Display the current version of openapi2aspida.

npx openapi2aspida -i=openApi/sample.yaml -o=lib/api/sample

The default export of openapi2aspida is a function used to generate aspida route files and types from OpenAPI/Swagger specifications. You can call this function without arguments to use the default configuration, or pass a PartialConfig object to override settings.

When executed, the function:

1. Resolves the configuration.
2. Ensures the output directory exists and is empty.
3. Builds the necessary templates and types.
4. Writes the generated route files to the specified output directory.

Note: If the destination path is not an empty directory, the process will log a fatal error and stop.

import openapi2aspida from 'openapi2aspida';

// Example: Running with custom configuration
await openapi2aspida({
  input: 'path/to/openapi.yaml',
  output: 'src/api',
  // ... other PartialConfig options
});