Swagger 문서 자동 생성

Application.run({
  name: 'my-api',
  basePath: 'api',
  swagger: {
    name: 'My API',
    version: '1.0.0',
    description: 'API 문서 설명',
    scheme: 'https',
    host: 'api.example.com',
    auth_url: '/auth/login',
    // 선택: Swagger UI 접근 제어
    useAuth: true,
    userObject: { admin: 'password123' },
  },
  // ...
});

@Post('/register', {
  title: '회원 가입',              // → summary
  description: '새로운 사용자 등록',  // → description
  deprecated: false,              // → deprecated
  auth: true,                     // → 런타임 JWT 미들웨어 제어 (Swagger에는 전역 security 적용)
  body: CreateUserDto,            // → requestBody schema
  bodyContentType: 'application/json',  // → requestBody content-type
  query: PaginationQueryDto,      // → parameters (in: query)
  response: UserInfoDto,          // → responses.200 schema
})

// 내부 변환 로직 (packages/router/src/express/router.ts)
// '/posts/:postId' → '/posts/{postId}'
const realPath = swaggerPath
  .split('/')
  .map((v) => (v.includes(':') ? `{${v.replace(':', '')}}` : v))
  .join('/');
 
// path 파라미터를 Swagger parameters에 추가
swaggerPath.split('/').forEach((v) =>
  v.includes(':') &&
  parameters.push({
    in: 'path',
    name: v.replace(':', ''),
    required: true,
    schema: { type: 'string' },
  })
);

parameters:
  - in: path
    name: postId
    required: true
    schema:
      type: string

// ExtendableDto.generateScheme() — 각 필드의 toSwagger()를 호출하여 스키마 생성
{
  type: 'object',
  properties: {
    id:    { type: 'integer', format: 'int32', description: 'User ID' },
    email: { type: 'string', description: 'Email' },
    name:  { type: 'string', description: 'Display name' },
  }
}
 
// ExtendableDto.swagger() — $ref 형태로 반환
{ $ref: '#/components/schemas/UserInfoDto' }

// 단일 타입
response: TypeIs.BOOLEAN()
 
// 배열 응답
response: TypeIs.ARRAY(PostInfoDto)
 
// 페이지네이션 응답
response: TypeIs.PAGING(PostInfoDto)

// packages/router/src/express/router.ts (간소화)
if (body !== undefined) {
  if (isClass(body)) {
    // DTO 클래스 → swagger() 호출 → $ref 스키마
    const data = new body().swagger();
    result.requestBody = this.generateRequestBody(
      this.generateDtoScheme(data, 'Body'),
      bodyContentType
    );
  } else {
    // TypeIs.* 함수 → toSwagger() 호출
    const type = body();
    if (['array', 'paging'].includes(type?.__name)) {
      result.requestBody = this.generateRequestBody(
        this.generateDtoScheme(type?.toSwagger?.(), 'Body'),
        bodyContentType
      );
    } else {
      result.requestBody = this.generateRequestBody(
        this.generateTypeScheme(body, 'Body'),
        bodyContentType
      );
    }
  }
}

// @asapjs/core — 전역 Swagger 스키마 레지스트리
export function addScheme(data: { name: string; data: any }): void { ... }
export function generateSchemeRefWithName(name: string): string { ... }
 
// @asapjs/router/src/swagger/index.ts — path 및 최종 JSON 관리
class DocsApplication {
  public swaggerData = { ...defaultSwagger };  // OpenAPI 3.0 기본 구조
  private swaggerPath = [];    // 등록된 path 정보
 
  // 라우트 등록 시 호출
  public addPaths = async (data: any) => { ... };
 
  // 첫 요청 시 최종 Swagger JSON 조합 (core의 스키마 레지스트리 사용)
  public generateSwaggerData = (req: any) => { ... };
 
  // 캐시된 데이터 반환 (없으면 generate 호출)
  public getSwaggerData = (req: any) => { ... };
}
 
export const { addPaths, getSwaggerData } = new DocsApplication();
export { addScheme, generateSchemeRefWithName } from '@asapjs/core';

// 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),
  );
}

@router SWAGGER useAuth is disabled! Please add config.swagger.useAuth & config.swagger.userObject

{
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      },
      "OAuthLogin": {
        "type": "oauth2",
        "flows": {
          "password": {
            "tokenUrl": "/auth/login",
            "scopes": {}
          }
        }
      }
    }
  }
}

import { RouterController, Get, Post, Put, Delete, ExecuteArgs } from '@asapjs/router';
import { PaginationQueryDto, TypeIs } from '@asapjs/sequelize';
import CreatePostDto from '../dto/CreatePostDto';
import UpdatePostDto from '../dto/UpdatePostDto';
import PostInfoDto from '../dto/PostInfoDto';
 
export default class PostController extends RouterController {
  public tag = 'Post';        // Swagger 태그 그룹
  public basePath = '/posts';  // URL 접두사
 
  constructor() {
    super();
    this.registerRoutes();     // 여기서 Swagger 스키마도 함께 등록
    this.postService = new PostApplication();
  }
 
  // Swagger: GET /posts
  //   - query parameters: page, limit
  //   - response: PostInfoDto_PAGING 스키마
  @Get('/', {
    title: '게시글 목록 조회',
    description: '게시글 목록을 조회합니다',
    query: PaginationQueryDto,
    response: TypeIs.PAGING(PostInfoDto),
  })
  async getPosts({ paging }: ExecuteArgs) { ... }
 
  // Swagger: POST /posts
  //   - auth: true → 런타임 JWT 미들웨어 적용 (Swagger에는 전역 security)
  //   - requestBody: CreatePostDto 스키마
  //   - response: PostInfoDto 스키마
  @Post('/', {
    title: '게시글 작성',
    auth: true,
    body: CreatePostDto,
    response: PostInfoDto,
  })
  async createPost({ body, user }: ExecuteArgs) { ... }
 
  // Swagger: GET /posts/{postId}
  //   - path parameter: postId (자동 감지)
  //   - response: PostInfoDto 스키마
  @Get('/:postId', {
    title: '게시글 상세 조회',
    response: PostInfoDto,
  })
  async getPost({ path }: ExecuteArgs) { ... }
 
  // Swagger: DELETE /posts/{postId}
  //   - auth: true → 런타임 JWT 미들웨어 적용 (Swagger에는 전역 security)
  //   - path parameter: postId (자동 감지)
  @Delete('/:postId', {
    title: '게시글 삭제',
    auth: true,
  })
  async deletePost({ path, user }: ExecuteArgs) { ... }
}