Swagger 데코레이터는 문서에 남길 계약 위치로 고른다
문서 품질은 DTO 필드 설명, 컨트롤러 응답, 인증 요구 사항이 코드와 같이 움직일 때 높아진다.
| 위치 | 데코레이터 | 문서에 남는 정보 |
|---|---|---|
| DTO 필드 | @ApiProperty |
필드 타입, 예시, 필수 여부 |
| Controller method | @ApiOperation |
엔드포인트 목적과 요약 |
| Response | @ApiResponse |
상태 코드별 성공과 실패 형식 |
| Auth route | @ApiBearerAuth |
JWT 인증이 필요한 API 표시 |
핵심: 문서만 따로 꾸미지 말고 실제 DTO와 컨트롤러 계약을 드러내는 방식으로 붙인다.