Swagger

Swagger가 필요한 이유

swagger는 api를 사용하는 사람들에게 제공하는 설명서입니다.
프론트 개발자는 api를 호출하고 데이터를 불러오는 일을 할 때 백엔드 개발자에게 요청을 어떻게 보내야하는지 응답의 종류는 무엇이 있는지를 매번 물어본다면 능률이 떨어질 것입니다.
다른 예로는 OpenAPI를 사용하는데 어떻게 사용하는지 나와있지 않다면 누구도 이용할 수 없을 것입니다.
위와같은 이유로 API 명세서를 만든다고 한다면 개발자는 요청변수와 응답값에 대한 설명을 작성하는 것도 반복적인 작업이 많아지기 때문에 Swagger를 사용하는 것으로 소스코드에서 명세서를 같이 작성해 반복적인 작업을 줄일 수 있습니다.  Swagger는 API의 사용법과 Test할 수 있는 기능을 제공함으로써 API의 사용을 편리하게 만들어줍니다

 

Swagger 사용법

Spring Boot3부터는 Swagger UI가 제대로 동작하지 않기 때문에 SpringDocs를 사용하겠습니다.
Swagger는 어노테이션을 사용해 선언적 형태로 명세서를 작성할 수 있습니다.

 

@Tag

Tag 어노테이션은 api의 end point가 어떤 그룹에 속하는지 알려주는 어노테이션입니다.
즉, 회원에 관한것인지와 같이 어떤기능에 속하는지 알려주는 어노테이션입니다.
속성값으로 가장 많이 사용하는 것은 name,description입니다.
아래 사진과 같은 형태로 작성시 swagger-ui에 아래와 같이 표시됩니다.

 

@Operation

API에 대한 반환값, 설명 등을 나타내는 어노테이션입니다.
아래 사진과 같이 Controller의 메서드를 설명해주는 어노테이션입니다.
response 속성을 사용해 응답 값을 원하는 형태로 만들 수도 있습니다.

 

@Schema

요청 DTO, 응답 DTO를 설명하는 어노테이션입니다.
@Schema()의 description 속성을 통해 각 DTO의 필드값에 설명을 작성하고 example 속성값을 사용해서 
아래 사진과 같이 예시 값으로 넣을 수 있습니다