[SpringBoot] Swagger 기능 사용을 위한 설정 및 예제 코드

Swagger(스웨거)는 RESTful API 서비스를 편리하게 문서화 해주고, 이를 통해서 관리 및 제 3의 사용자가 편리하게 API를 호출하고 테스트할 수 있도록 해주는 도구이다.

Swagger 의존성 추가

Swagger를 사용하기위해 pom.xml에 라이브러리를 추가해준다.

/* Spring Boot – Maven */
<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-annontations</artifactId>
    <version>2.2.21</version>
</dependency>

Swagger-UI 그룹화방법

API 클래스에 @Tag 어노테이션을 사용하면되는데, 같은 구룹으로 묶고자하는 경우 API 클래스에 @Tag 어노테이션내 name값을 동일하게 설정하면 된다.

이때 class  또는 method에 선언하면된다.

예시 : testCallApi.java

@RequestMapping(“/test/select”)

@RequiredArgConstructor

@Tag(name=”공통 조회”, descrption=”공통 조회 API 그룹” )

public class testCallApi {

   ….생략

}

파라미터 정보 설정

Swagger-UI에서 schema 버튼을 클릭하여 확인 가능하다. 그러려면 DTO에 @Schema 어노테이션을 사용하여   컬럼설명과 null 가능여부,길이 등을 지정해야 된다.

예시 : test Dto.java

@AllArgConstructor

@Builder

@Data

@NoArgConstructor

public class TestDto implements Serializable {

      @Schema(description=”코드ID”, nullable=false, maxLengrh= 40)

     private String codeId;

}

API 설명 추가하기

Api 메서드에 @Operation 어노테이션을 사용하여 summary 와 description 을 지정해준다.

예시 : testCallApi.java

…이상 생략

public class testCallApi {

   private final TestContorller cntr;

   @ Operation (summary=”리스트”, description=”코드ID로 코드명조회”)

    public TestDto selectBase(@RequestBody TestQryDto) {

        ……생략

    }

}

스웨거 공식사이트 : https://swagger.io/