@new_superfi/nestjs-swagger-typescript-viewer

A library that adds TypeScript interface viewer functionality to NestJS Swagger UI. It automatically converts OpenAPI schemas to TypeScript interfaces, allowing you to view Request/Response types in TypeScript format within Swagger UI.

Installation

npm install @new_superfi/nestjs-swagger-typescript-viewer
# or
yarn add @new_superfi/nestjs-swagger-typescript-viewer
# or
pnpm add @new_superfi/nestjs-swagger-typescript-viewer

Peer Dependencies

This package requires the following packages as peer dependencies:

• @nestjs/common: ^10.0.0 || ^11.0.0
• @nestjs/core: ^10.0.0 || ^11.0.0
• @nestjs/swagger: ^10.0.0 || ^11.0.0

Quick Start

import { NestFactory } from "@nestjs/core";
import { DocumentBuilder, SwaggerModule } from "@nestjs/swagger";
import { setupSwaggerWithTypeScript } from "@new_superfi/nestjs-swagger-typescript-viewer";
import { AppModule } from "./app.module";

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const config = new DocumentBuilder()
    .setTitle("My API")
    .setDescription("API description")
    .setVersion("1.0")
    .build();

  const document = SwaggerModule.createDocument(app, config);

  // Use setupSwaggerWithTypeScript instead of SwaggerModule.setup
  setupSwaggerWithTypeScript(app, "api", document);

  await app.listen(3000);
}
bootstrap();

Usage

Basic Setup

setupSwaggerWithTypeScript(
  app: INestApplication,
  path: string,
  document: OpenAPIObject,
  options?: SwaggerTypeScriptOptions
): void;

Options

interface SwaggerTypeScriptOptions {
  path?: string; // Swagger UI path (default: uses the path passed as the first argument)
  customCss?: string; // Custom CSS
  swaggerOptions?: any; // Additional Swagger UI options
}

Example: Using Custom Options

setupSwaggerWithTypeScript(app, "api", document, {
  customCss: ".swagger-ui { max-width: 1200px; }",
  swaggerOptions: {
    persistAuthorization: true,
    displayRequestDuration: true,
  },
});

Examples

DTO Example

// user.dto.ts
import { ApiProperty } from "@nestjs/swagger";

export class CreateUserDto {
  @ApiProperty({ description: "User name" })
  name: string;

  @ApiProperty({ description: "Email", required: false })
  email?: string;

  @ApiProperty({ description: "Age", type: Number })
  age: number;
}

export class UserResponseDto {
  @ApiProperty({ description: "User ID" })
  id: number;

  @ApiProperty({ description: "User name" })
  name: string;

  @ApiProperty({ description: "Email" })
  email: string;
}

When using DTOs like the above, TypeScript interfaces are automatically generated and displayed in Swagger UI:

interface CreateUserDto {
  name: string;
  email?: string;
  age: number;
}

interface UserResponseDto {
  id: number;
  name: string;
  email: string;
}

NestJS Swagger UI에 TypeScript 인터페이스 뷰어 기능을 추가하는 라이브러리입니다. OpenAPI 스키마를 자동으로 TypeScript 인터페이스로 변환하여 Swagger UI에서 Request/Response 타입을 TypeScript로 확인할 수 있습니다.

설치

npm install @new_superfi/nestjs-swagger-typescript-viewer
# 또는
yarn add @new_superfi/nestjs-swagger-typescript-viewer
# 또는
pnpm add @new_superfi/nestjs-swagger-typescript-viewer

Peer Dependencies

이 패키지는 다음 패키지들을 peer dependency로 요구합니다:

• @nestjs/common: ^10.0.0 || ^11.0.0
• @nestjs/core: ^10.0.0 || ^11.0.0
• @nestjs/swagger: ^10.0.0 || ^11.0.0

빠른 시작

import { NestFactory } from "@nestjs/core";
import { DocumentBuilder, SwaggerModule } from "@nestjs/swagger";
import { setupSwaggerWithTypeScript } from "@new_superfi/nestjs-swagger-typescript-viewer";
import { AppModule } from "./app.module";

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const config = new DocumentBuilder()
    .setTitle("My API")
    .setDescription("API description")
    .setVersion("1.0")
    .build();

  const document = SwaggerModule.createDocument(app, config);

  // 기존 SwaggerModule.setup 대신 setupSwaggerWithTypeScript 사용
  setupSwaggerWithTypeScript(app, "api", document);

  await app.listen(3000);
}
bootstrap();

사용법

기본 설정

setupSwaggerWithTypeScript(
  app: INestApplication,
  path: string,
  document: OpenAPIObject,
  options?: SwaggerTypeScriptOptions
): void;

옵션

interface SwaggerTypeScriptOptions {
  path?: string; // Swagger UI 경로 (기본값: 첫 번째 인자로 전달된 path 사용)
  customCss?: string; // 커스텀 CSS
  swaggerOptions?: any; // Swagger UI 추가 옵션
}

예제: 커스텀 옵션 사용

setupSwaggerWithTypeScript(app, "api", document, {
  customCss: ".swagger-ui { max-width: 1200px; }",
  swaggerOptions: {
    persistAuthorization: true,
    displayRequestDuration: true,
  },
});

예제

DTO 예제

// user.dto.ts
import { ApiProperty } from "@nestjs/swagger";

export class CreateUserDto {
  @ApiProperty({ description: "사용자 이름" })
  name: string;

  @ApiProperty({ description: "이메일", required: false })
  email?: string;

  @ApiProperty({ description: "나이", type: Number })
  age: number;
}

export class UserResponseDto {
  @ApiProperty({ description: "사용자 ID" })
  id: number;

  @ApiProperty({ description: "사용자 이름" })
  name: string;

  @ApiProperty({ description: "이메일" })
  email: string;
}

위와 같은 DTO를 사용하면 Swagger UI에서 자동으로 TypeScript 인터페이스가 생성되어 표시됩니다:

interface CreateUserDto {
  name: string;
  email?: string;
  age: number;
}

interface UserResponseDto {
  id: number;
  name: string;
  email: string;
}

Contributing

Contributions are welcome! Please contribute through issue reports or Pull Requests.

• Issue Reports: GitHub Issues
• Repository: GitHub Repository

License

MIT License

Copyright (c) 2025 new_superfi