đź“– Guide Documents
Swagger to NestJS

Swagger to NestJS

Outline

⚠️

Supports OpenAPI v3.0 only.

Terminal
# SETUP GLOBALLY
npm install -g @nestia/migrate
 
# DO MIGRATE
npx @nestia/migrate swagger.json output_directory

@nestia/migrate converts swagger.json file to a NestJS project.

When you run npx @nestia/migrate swagger.json <output> command, @nestia/migrate will analyze your swagger.json file, and generate a NestJS project into the <output> direcory. If you're considering to migrate your backend project to NestJS, @nestia/migrate will be a good starting point.

Also, @nestia/sdk can generate below things from NestJS project.

It means that, with @nestia/migrate, you can generate SDK Library or Mockup Simulator from every backend projects. If you don't have plan to migrate to NestJS, but hope to take advantages of it, @nestia/migrate will be a good choice. Languages and frameworks, they're no longer matter in backend development. Let's enjoy the new world with @nestia/migrate.

SDK

  • Left is NestJS code converted from @nestia/migrate
  • Right is client side code utilizing SDK generated by @nestia/sdk

Setup

Terminal
# SETUP GLOBALLY
npm install -g @nestia/migrate
 
# DO MIGRATE
npx @nestia/migrate swagger.json output_directory

At first, install @nestia/migrate globally.

After that, run npx @nestia/migrate <input> <output> command. The first <input> argument must be target swagger.json file, and the second <output> argument must be output directory to be a NestJS project. When you run that command, @nestia/migrate will analyze your swagger.json file, and generate a NestJS project into the <output> direcory.

By the way, @nestia/migrate supports only OpenAPI v3.0 specification. If you have a swagger.json file with OpenAPI v1 or v2 specification, you can't convert it to a NestJS project. In that case, rebuild the swagger.json file from your backend project, specifying OpenAPI v3.0 specification.

Generated NestJS Project

src/api/functional/body/index.ts
/**
 * @packageDocumentation
 * @module api.functional.body
 * @nestia Generated by Nestia - https://github.com/samchon/nestia 
 */
//================================================================
import { Fetcher } from "@nestia/fetcher";
import type { IConnection } from "@nestia/fetcher";
import typia from "typia";
 
import { NestiaSimulator } from "./../../utils/NestiaSimulator";
import type { IBbsArticle } from "./../../structures/IBbsArticle";
 
/**
 * @controller BodyController.post()
 * @path POST /body
 * @nestia Generated by Nestia - https://github.com/samchon/nestia
 */
export async function post(
    connection: IConnection,
    body: IBbsArticle.IStore,
): Promise<post.Output> {
    return !!connection.simulate
        ? post.simulate(
              connection,
              body,
          )
        : Fetcher.fetch(
              connection,
              post.ENCRYPTED,
              post.METHOD,
              post.path(),
              body,
          );
}
export namespace post {
    export type Input = IBbsArticle.IStore;
    export type Output = IBbsArticle;
 
    export const METHOD = "POST" as const;
    export const PATH: string = "/body";
    export const ENCRYPTED: Fetcher.IEncrypted = {
        request: false,
        response: false,
    };
 
    export const path = (): string => {
        return `/body`;
    }
    export const random = (g?: Partial<typia.IRandomGenerator>): Output =>
        typia.random<Output>(g);
    export const simulate = async (
        connection: IConnection,
        body: post.Input,
    ): Promise<Output> => {
        const assert = NestiaSimulator.assert({
            method: METHOD,
            host: connection.host,
            path: path()
        });
        assert.body(() => typia.assert(body));
        return random(
            typeof connection.simulate === 'object' &&
                connection.simulate !== null
                ? connection.simulate
                : undefined
        );
    }
}

Newly generated NestJS project by @nestia/migrate would form like above.

At first, every controllers would be generated following URL path hierarchy. Also, typia.random<T>() (opens in a new tab) function would be utilized in every route methods to generate random data following specific response DTO type. SDK library and Mockup simulator also utilize the typia.random<T>() (opens in a new tab) function too.

As you can see from above example case, @nestia/migrate perfectly revives every DTO types and route methods, but it doesn't revive business logics. It means that, you have to implement business logics by yourself. Of course, it's not a matter if you're utilizing @nestia/migrate not for real NestJS migration, but for generating SDK library and Mockup simulator only.

Nestia Editor

I'm making a new library named @nestia/editor.

It's a type of evolved swagger-ui, embedding TypeScript Editor, @nestia/migrate and @nestia/sdk.

By embedding TypeScript Editor in swagger-ui, you can take advatanges of TypeScript compiler like type hints and auto-completions. Also, if you turn on simulation mode, @nestia/editor will utilize embeded Mockup Simulator of @nestia/sdk, instead of sending request to the real backend server.

Of course, as @nestia/editor includes @nestia/migrate, you can build and download SDK library and Mockup Simulator in the website.

Look forward to it, I'll show you a new world.