New NestJS Swagger Generator evolved than ever

New NestJS Swagger Generator

import { NestiaSwaggerComposer } from "@nestia/sdk";
import { INestApplication } from "@nestjs/common";
import { NestFactory } from "@nestjs/core";
import { SwaggerModule } from "@nestjs/swagger";

const main = async (): Promise<void> => {
  const app: INestApplication = await NestFactory.create(ApplicationModule);
  const document = await NestiaSwaggerComposer.document(app, {
    openapi: "3.1",
    servers: [
      {
        url: "http://localhost:3000",
        description: "Localhost"
      }
    ]
  });
  SwaggerModule.setup("api", app, document as any);
  await app.listen(3_000);
};
main().catch(console.error);

OpenAPI (Swagger) document generator for NestJS evolved than ever.

@nestia/sdk automatically analyzes the NestJS source code in the compilation level, and makes the OpenAPI document without any extra dedication like @nestjs/swagger decorator function calls. Everything is automated in the @nestia/sdk.

Let's setup @nestia/sdk, and take advantages of it.

npx nestia setup --runtime

• Github Repository: https://github.com/samchon/nestia
• Guide Documents: https://nestia.io/docs/sdk/swagger/#runtime-composition

DTO Schema

//----
// JUST FINE WITH INTERFACE TYPE in @nestia/sdk
//----
export interface IBbsArticle {
  /**
   * List of attachment files.
   */
  files: null | IAttachmentFile[];
}

//----
// NEEDS TUPLE DUPLICATED DEFINITIONS IN @nestjs/swagger
//----
export class BbsArticle {
  // DUPLICATED SCHEMA DEFINITION
  // - duplicated function call + property type
  // - have to specify `isArray` and `nullable` props by yourself
  @ApiProperty({
    type: () => AttachmentFile,
    nullable: true,
    isArray: true,
    description: "List of attached files.",
  })
  @Type(() => AttachmentFile)
  @IsArray()
  @IsOptional()
  @IsObject({ each: true })
  @ValidateNested({ each: true })
  files: null | AttachmentFile[];
}

Look at the below example DTO (Data Transfer Object) schemas used in both @nestia/sdk and @nestjs/swagger. Which one seems convenient? As you can see, @nestia/sdk needs only pure TypeScript type. Besides, @nestjs/swagger requires triple duplicated type definitions on the DTO schema.

Considering the safety, @nestia/sdk is much useful. Because of the triple duplicated definitions in the @nestjs/swagger utilizing DTO schema, productivity and maintainability are reduced, and lead the users to take mistake. What’s worse, if you misuse @nestjs/swagger decorators, even if they differ from actual TypeScript types, no compilation errors occur. Besides, @nestia/sdk needs only pure TypeScript types, so that no problem like @nestjs/swagger at all.

This is the reason why you should adapt the @nestia/sdk for OpenAPI generation in the NestJS. @nestia/sdk will analyze your TypeScript DTO types in the compilation level, and composes JSON schema of the OpenAPI specification automatically. You can take productivity, maintainability and safety at all just by using it.

Software Development Kit

Left is the NestJS server code, and right is the client code utilizing the SDK.

If you setup @nestia/sdk, you can make not only OpenAPI (Swagger) document, but SDK (Software Development Kit) library for the client developers which has gathered fetch() functions with strict type definitions.

As you can see from the above image's right side, client programmer can easily develop the API interaction program very conveniently and safelty through the SDK library. The SDK library also generated by the compilation level TypeScript source code analyzing by the @nestia/sdk.

If you've succeeded to build up OpenAPI document by @nestia/sdk, let's challenge to the SDK (Software Development Kit) library generation, too.

Swagger-UI + TypeScript Editor

https://nestia.io/docs/editor/

If you've suceeded to build the OpenAPI (Swagger) document, you may provide it to the companion developers through Swagger-UI. By the way, how aboout combinating the Swagger-UI with online TypeScript editor embedding the SDK (Software Development Kit) library?

Just visit above website (https://nestia.io/docs/editor/) and put down the swagger file to there. Then, online TypeScript editor (of StackBlitz) combined Swagger-UI would be opened, and client developers can utilize it much efficiently.