[ Spring-Boot ] Swagger 사용하기

안녕하세요 이번 글에서는 Swagger를 사용하여 보겠습니다.

 

Swagger란? 

간단하게 정리하면 API스펙 문서 또는 개발자에게 필요한  documentation Page입니다.

 

사용방법에 앞서 먼저 보여드리자면 

이런 식으로 서버를 실행시킨 다음  http://localhost:8080/swagger-ui.html( IP와 PORT는 변경될 수 있습니다.)

접속하게 되면 서버의 프로세스를 확인할 수 있습니다.

 

먼저 Swagger를 사용하기 위해 라이브러리를 추가하겠습니다.

아래 코드를 입력 한 다음 빌드하여 줍시다.

 

Maven

 <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

 

Gradle

// https://mvnrepository.com/artifact/io.springfox/springfox-swagger2
implementation group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2'

// https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui
implementation group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'

 

Swagger를 사용하기 위해 클래스를 생선 한 뒤 @Configuration 선언하여 설정을 만들어 줍니다.

/**
 * Swagger 설정
 */
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
    @Bean
    public Docket docket() {
        ApiInfoBuilder apiInfo = new ApiInfoBuilder();
        apiInfo.title("API 서버 문서"); //Swagger 문서의 타이틀
        apiInfo.description("API 서버 문서 입니다."); // Swagger 문서의 간략 설명

        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        docket.apiInfo(apiInfo.build());                                                    // 문서로 만들 Controller 패키지 경로 설정
        ApiSelectorBuilder apis = docket.select().apis(RequestHandlerSelectors.basePackage("kr.co.song.spring.mvc.controller"));
        apis.paths(PathSelectors.ant("/**")); // Controller 에서 보여줄 맵핑값 설정 
        return apis.build();
    }
}

 

그다음 Swagger를 사용할 Controller에서 Swagger 관련 어노테이션을 선언하여 줍시다.

먼저 Class에 @Api를 선언하여 줍니다.

 

@Api(tags = "게시판 API") //Swagger 문서 태그
public class BoardControlle

 

Swagger에 등록할 메서드에 @ApiOperation를 선언하여 줍시다.

 

 @ApiOperation(value = "목록 조회", notes="게시물 전체 목록 조회.")
    public BaseResponse<List<Board>>  getList

 

해당 메서드에 파라미터를 등록하고 싶다면  @ApiParam 또는 @ApiImplicitParams 사용하여 줍니다.

 

@ApiParam'

 @ApiOperation(value = "목록 조회", notes="게시물 전체 목록 조회.")
    public BaseResponse<List<Board>>  getList(
            @ApiParam BoardSearchParameter parameter,
            @ApiParam MySQLPageRequest pageRequest
            )

파라미터 앞에 선언하여 준다. 

 

 @ApiImplicitParams

@ApiOperation(value = "상세 조회", notes="게시물 번호에 해당하는 상세 정보를 조회할 수 있습니다.")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "boardSeq",value = "게시물 번호",example = "1")
    })
    public BaseResponse<Board> get(){
   

위처럼 메서드 위에 선언하여 사용한다. 

 

Swagger 사용법을 간단히 정리하여 보았습니다.

 

감사합니다.