npm package: @new_superfi/nestjs-swagger-typescript-viewer
Description: NestJS Swagger TypeScript interface viewer
Author: new_superfi
Latest version: 1.0.3

# @new_superfi/nestjs-swagger-typescript-viewer

[![npm version](https://img.shields.io/npm/v/@new_superfi/nestjs-swagger-typescript-viewer.svg)](https://www.npmjs.com/package/@new_superfi/nestjs-swagger-typescript-viewer)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Changelog](https://img.shields.io/badge/Changelog-View-blue)](./CHANGELOG.md)

<img width="853" height="1250" alt="image" src="https://github.com/user-attachments/assets/5b639fae-1bd0-4e9f-8910-4bfd53efd5cf" />

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

```bash
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

```typescript
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

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

### Options

```typescript
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

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

## Examples

### DTO Example

```typescript
// 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:

```typescript
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로 확인할 수 있습니다.

## 설치

```bash
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

## 빠른 시작

```typescript
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();
```

## 사용법

### 기본 설정

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

### 옵션

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

### 예제: 커스텀 옵션 사용

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

## 예제

### DTO 예제

```typescript
// 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 인터페이스가 생성되어 표시됩니다:

```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](https://github.com/newsuperfi/nestjs-swagger-typescript-viewer/issues)
- **Repository**: [GitHub Repository](https://github.com/newsuperfi/nestjs-swagger-typescript-viewer)

## License

MIT License

Copyright (c) 2025 new_superfi