OpenAPI Metadata

Swagger 데코레이터는 문서의 빈칸을 채우는 위치가 다르다

DTO에는 데이터 모양을, 컨트롤러에는 작업 의미와 응답 상태를 적어야 Swagger UI가 호출 가능한 계약이 된다.

DTO에 붙이는 정보

schema
@ApiProperty

필드 설명과 예시

name, email, age의 타입과 예시가 Schemas 영역에 표시된다.

PartialType

수정 입력 재사용

Create DTO의 문서 정보를 Update DTO로 이어받아 중복을 줄인다.

컨트롤러에 붙이는 정보

operation
@ApiOperation

엔드포인트 목적

목록 조회, 생성, 수정, 삭제 같은 동작을 태그 아래에서 읽게 한다.

@ApiResponse

성공과 실패 기대값

200, 201, 400, 404 같은 상태와 반환 타입을 명확히 남긴다.