Overview

---

프로젝트 내에서 api 정보를 공유할 때 문서보다 Swagger UI가 편리하다.
아래는 기본적인 어노테이션들을 적어보았다.
궁금한 내용은 여기서 별도 검색하고, 메서드, 클래스, vo에 어떤 어노테이션을 쓰는 지 위주로 보면 좋을 것 같다.

@Tag – swagger api 리스트 상단 헤더

• name : 상단 헤더 이름
• description : 헤더에 대한 설명

@Schema – model에 대한 정보, 클래스 전체 또는 iv에 위치 (dto, vo)

• description : model 객체에 대한 설명
• defaultValue : 기본값
• allowableValues : 허용 가능한 값들을 정의
• example : 예시 설명

@Operation – api 상세 정보 설정

• summary : api 요약 설명 (api 바로 오른쪽에 위치)
• description : api 상세 설명 (api 바로 아래에 위치)
• response : api 응답 리스트
• parameters : api 파라미터 리스트

@Parameter – api 파라미터

• name : 파라미터 이름
• description : 파라미터 설명
• in
  • query : 쿼리 파라미터 표시 (/test?role=admin)
  • header : http 헤더 파라미터 표시
  • path : 경로 파라미터 표시 (/tests/{id})
  • cookie : 쿠키 헤더 표시

@Hidden – api 숨김 처리

@ApiOperation – api 단일 작업을 설명,  기본 코드 200

• hidden : api 숨김 여부 처리
• value : 작업 내용 설명
• response : 응답 모델 객체를 연결

@Api – swagger api 상단 헤더

• tags : swagger api 리스트 상단 헤더명 지정

@ApiParam – 파라미터의 메타 데이터 지정

• value : 값 지정

@ApiImplicitParam – 해당 api 메서드의 파라미터 설명 추가

• name : 파라미터 이름
• value : 값
• required : 필수 여부
• dataType : 데이터 타입
• paramType : 파라미터 타입 (예: path)
• defaultValue : 기본값 설정

@ApiImplicitParams - @ApiImplicitParam을 복수 개 사용

예) @ApiImplicitParams({@ApiImplicitParam(), @ApiImplicitParam(), …})

@ApiResponse – api 응답 정보 설정

• responseCode : response http 상태코드
• description : response에 대한 설명
• content : response payload 구조
• schema : content에서 사용하는 스키마 구조
  • hidden : Schema 숨김 여부
  • implementation : Schema가 구현할 model(dto, vo)

@ApiModel – model 설명

@ApiModelProperty – model의 iv 설명

• example : 예시 설명
• value : 값
• name : 이름
• dataType : 데이터 타입(예: String)