swagger v3 사용 방법 정리

swagger

• API 설계, 문서화 및 테스트를 위한 오픈소스 프레임워크
• 주로 RESTfulAPI를 문서화하고 관리하는 데 사용
• JSON 또는 YAML 형식으로 API 정의를 작성하고 이를 사용하여 문서를 생성하는 방법을 제공

-> API 엔드포인트, 요청 및 응답형식, 인증 방법 및 예제 제공

사용 방법

1. Controller에 @Tag 어노테이션 사용해서 api 그룹 설정하기
   
   설정 전 : 컨트롤러 이름 그대로, 옆에 설명 없음

• name : 태그 이름
• description : 태그 설명
  추가 후 모습

@Tag(name = "~", description = "설명")
@Tag(name = "~", description = "설명")

각각 붙여놓기

2. @Schema 설정하기

• description : 게시물 제목

• defaultValue : 디폴트 제목

• allowableValues : 가능한 값들

  모델(Model) 정보 작성함
  

  모델 값별로 설명을 붙일 수 있다
  class 전체에 @Schema(name = "")으로 스키마 이름 붙임
  descrpiton 으로 상세설명 붙임
  

  description정도 잘 써주면 될 것 같다....
  

3. API 컨트롤러 상세정보 설정 -> @Operation

• summary : api 관련 간략한 설명
• description : api 상세 설명
• response : api Response 리스트
• parameter : api 파라미터 리스트

    @Operation(
        summary = "~~~",
        responses = [
            ApiResponse(
                responseCode = "200",
                description = "OK"
            )
        ]
    )

controller 마다 붙인다

4. 파라미터 설명 붙이기 ->@Parameter

• name : 파라미터 이름
• description : 파라미터 설명
• value : 실제 들어갈 값
  

Parameter(
            name = "~",
            description = "~",
            examples = [
                ExampleObject(value = "SUBSCRIPTION", name = "구독"),

            ]
        )

value와 name만 잘 설정하면 된다..!