OpenAPI decorator

Swagger 데코레이터 선택 기준

Swagger 문서 품질은 DTO 필드 설명, 컨트롤러 응답, 인증 요구 사항이 코드와 같이 움직일 때 높아진다.

문서 계약
위치데코레이터문서에 남는 정보
DTO 필드@ApiProperty필드 타입, 예시, 필수 여부
Controller method@ApiOperation엔드포인트 목적과 요약
Response@ApiResponse상태 코드별 성공과 실패 형식
Auth route@ApiBearerAuthJWT 인증이 필요한 API 표시
문서만 따로 꾸미는 것이 아니라 실제 DTO와 컨트롤러 계약을 드러내는 방식으로 붙인다.