Open API 3.0 Swagger v3 상세설정(23/01/08)

이전 포스팅에서 swagger 기능에 대해 다룬적이 있다.

아래 참고사이트에서 확인할수 있다.

 

이번 포스팅에서는 swagger 를 좀더 상세설정을 통해서 사용할수 있는 기능을 몇가지 적어보려고 한다.

 

api 그룹 설정 (@Tag)

restcontroller 의 서비스에 @Tag annotation 을 달아서 그룹화를 할수 있다.

name 이 같은것끼리 swagger 에서 묶여서 보여진다.

• name: 태그의 이름
• description: 태그에 대한 설명

@Tag(name = "group", description = "그룹화 예제")

 

이렇게 달게 되면 된다.

 

api dto 설정 (@Schema)

swagger 로 받을 dto 값에 대한 스펙을 적어둘수 있다.

dto에서 컬럼마다 설정을 하며 

• description : 한글명
• defaultValue : 기본값
• allowableValues 

  @Schema(description = "게시물 제목", defaultValue = "디폴트 제목", allowableValues = {"게시물1", "게시물2"})

 

이렇게 달게 되면 된다.

api 상세 정보 설정 (@Operation)

swagger 에서 보이는 api에 상세 정보 설정이나 설명을 추가할수 있다.

• summary: api에 대한 간략한 설명
• description: api에 대한 상세 설명
• response: api Response 리스트
• parameters: api 파라미터 리스트

@Operation(summary = "게시물 등록", description = "제목(title)과 내용(content)을 이용하여 게시물을 신규 등록합니다.")

 

이렇게 달게 되면 된다.

---

참고 포스팅

https://thenicesj.tistory.com/252

swagger-ui 사용법