Skip to Content
API 레퍼런스@asapjs/routerSwagger

Swagger

이 페이지에서 찾을 수 있는 것

심볼분류설명
addPathsFunctionSwagger 경로 정보 등록
addSchemeFunctionSwagger 스키마 정보 등록
getSwaggerDataFunction최종 OpenAPI 스펙 반환
generateSchemeRefWithNameUtility$ref 문자열 생성
getSchemeNameFromRefUtility$ref에서 스키마 이름 추출

개요

ASAPJS는 라우트 데코레이터와 DTO/TypeIs 정의로부터 OpenAPI 3.0 스펙을 자동으로 생성합니다. 별도의 Swagger 파일을 작성할 필요 없이, 코드가 곧 API 문서가 됩니다.

import { addPaths, addScheme, getSwaggerData } from '@asapjs/router';

addPaths

Swagger 경로(path) 정보를 등록합니다. RouterController가 라우트 등록 시 내부적으로 호출하므로, 일반적인 사용에서는 직접 호출할 필요가 없습니다.

const addPaths: (data: any) => Promise<void>
파라미터타입설명
dataanySwagger 경로 객체. path, method, tags, summary, description, requestBody, responses, parameters 등을 포함합니다.

addScheme

Swagger 컴포넌트 스키마를 등록합니다. DTO와 TypeIs 타입이 Swagger에 표시되려면 이 함수를 통해 등록되어야 합니다. RouterController가 내부적으로 호출합니다.

const addScheme: (data: any) => Promise<void>
파라미터타입설명
dataany{ name: string, data: object } 형태. name은 스키마 이름, data는 OpenAPI 스키마 객체.

getSwaggerData

최종 OpenAPI 스펙을 반환합니다. 첫 호출 시 누적된 경로/스키마 데이터를 조합하여 스펙을 생성하고, 이후에는 캐시된 스펙을 반환합니다.

const getSwaggerData: (req: any) => any
파라미터타입설명
reqanyExpress Request 객체. req.headers.host를 서버 URL 생성에 사용합니다.

자동 생성 흐름

@Get/@Post/@Put/@Delete 데코레이터
    ↓
RouterController.excute()
    ↓ body/response DTO → generateSwaggerDefaultsSet()
    ↓
addPaths() + addScheme()  ← DocsApplication 싱글턴에 등록
    ↓
GET /docs/swagger.json 요청 시
    ↓
getSwaggerData(req) → 최종 OpenAPI JSON 반환

데코레이터 옵션 → OpenAPI 필드 매핑

데코레이터 옵션OpenAPI 필드설명
titlesummary엔드포인트 한 줄 설명
descriptiondescription상세 설명
deprecateddeprecated더 이상 사용되지 않는 엔드포인트 표시
bodyrequestBody요청 바디 스키마 (DTO 또는 TypeIs)
bodyContentTyperequestBody.contentapplication/json 또는 multipart/form-data
queryparameters쿼리 파라미터 스키마 (DTO)
responseresponses.200성공 응답 스키마 (DTO 또는 TypeIs)
errorsresponses.{status}에러 응답 스키마 (ErrorCreator 기반 자동 생성)
auth(Swagger 미반영)런타임 jwtVerification만 제어

auth와 Swagger security: auth: true는 런타임에서 JWT 토큰 검증을 수행하지만, Swagger 스펙에는 per-endpoint security 필드가 추가되지 않습니다. default-swagger.json에 정의된 전역 security(bearerAuth + OAuthLogin)가 모든 엔드포인트에 일괄 적용됩니다.

URL 파라미터 자동 변환

경로에 :param 형태의 파라미터가 있으면 OpenAPI path parameter로 자동 변환됩니다:

@Get('/:id', { title: '사용자 상세', response: UserInfoDto })
// Swagger: path: /users/{id}
// parameters: [{ in: 'path', name: 'id', required: true, schema: { type: 'string' } }]

Swagger 설정

IConfig.swagger 객체로 Swagger UI를 설정합니다:

필드타입필수설명
namestringYesSwagger UI 상단에 표시되는 API 이름
versionstringYesAPI 버전 문자열
descriptionstringYesAPI 설명 텍스트
scheme'http' | 'https'Yes”Try it out” 요청에 사용할 URL 스킴
hoststringYes”Try it out” 요청에 사용할 호스트
auth_urlstringNoOAuth2 Password Flow의 토큰 URL
useAuthbooleanNotrue일 때 Swagger UI 접근에 Basic Auth를 요구
userObject{ [username]: password }NoSwagger UI Basic Auth 사용자 계정

Swagger UI 접근

RouterPlugin이 부트스트랩 시 자동으로 등록하는 엔드포인트:

엔드포인트설명
/{basePath}/docs/swagger-ui.htmlSwagger UI 인터페이스
/{basePath}/docs/swagger.json생성된 OpenAPI 3.0 JSON 스펙

유틸리티 함수

generateSchemeRefWithName

OpenAPI $ref 문자열을 생성합니다.

import { generateSchemeRefWithName } from '@asapjs/router';
 
generateSchemeRefWithName('UserInfoDto');
// → '#/components/schemas/UserInfoDto'
const generateSchemeRefWithName: (schemeName: string) => string

getSchemeNameFromRef

$ref 문자열에서 스키마 이름을 추출합니다. generateSchemeRefWithName의 역연산입니다.

import { getSchemeNameFromRef } from '@asapjs/router';
 
getSchemeNameFromRef('#/components/schemas/UserInfoDto');
// → 'UserInfoDto'
const getSchemeNameFromRef: (ref: string) => string

Basic Auth 보호

프로덕션 환경에서는 Swagger UI를 외부에 노출하지 않도록 Basic Auth로 보호할 수 있습니다.

// packages/router/src/router/index.ts 에서 자동 처리
if (config?.swagger?.useAuth && config?.swagger?.userObject) {
  this.app.use(
    `/${basePath}/docs/swagger-ui.html`,
    basicAuth({
      users: config.swagger.userObject, // { admin: 'password' }
      challenge: true,
      realm: 'Developer',
    }),
    swaggerUi.serveFiles(undefined, options),
    swaggerUi.setup(undefined, options),
  );
}

useAuth: true와 userObject를 설정하면 Swagger UI 접근 시 브라우저 기본 인증 대화 상자가 나타납니다.

주의: useAuth를 설정하지 않으면 다음과 같은 경고 로그가 출력됩니다: @router SWAGGER useAuth is disabled! Please add config.swagger.useAuth & config.swagger.userObject

기본 OpenAPI 템플릿

DocsApplication은 다음 기본 구조에서 시작합니다:

{
  "openapi": "3.0.0",
  "servers": [],
  "info": { "version": "", "title": "", "description": "" },
  "paths": {},
  "components": {
    "schemas": {},
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer" },
      "OAuthLogin": {
        "type": "oauth2",
        "flows": {
          "password": { "tokenUrl": "/auth/login", "scopes": {} }
        }
      }
    }
  },
  "security": [
    { "OAuthLogin": [] },
    { "bearerAuth": [] }
  ]
}

내장된 보안 스킴:

  • bearerAuth — Authorization: Bearer <token> 헤더 방식
  • OAuthLogin — OAuth2 Password Flow (Swagger UI에서 직접 로그인 가능)

DTO → Swagger 스키마 변환

ExtendableDto를 상속한 DTO는 swagger() 메서드로 $ref 참조를 생성하고, generateScheme()으로 속성 스키마를 생성합니다.

DTO 정의와 생성되는 Swagger 스키마 예제:

export default class CreateUserDto extends ExtendableDto {
  @TypeIs.STRING({ comment: '이메일' })
  email: string;
 
  @TypeIs.PASSWORD({ comment: '비밀번호' })
  password: string;
 
  @TypeIs.STRING({ comment: '사용자 이름' })
  name: string;
}

생성되는 Swagger 스키마:

{
  "CreateUserDto": {
    "type": "object",
    "properties": {
      "email": { "type": "string", "description": "이메일" },
      "password": { "type": "string", "format": "password", "description": "비밀번호" },
      "name": { "type": "string", "description": "사용자 이름" }
    }
  }
}

관련 항목

Last updated on
RouterPlugin@asapjs/sequelize