[Spring] Swagger에 대해서 알아보자

Swagger는 RESTful API 문서화를 위한 도구로, API의 사용 방법과 API의 매개변수, 반환값 등을 문서로 정리해주는 역할을 합니다.

이번 글에서는 Spring Framework에서 Swagger를 사용하는 방법을 소개하겠습니다.

 

Swagger 추가

먼저 Swagger를 사용하기 위해 build.gradle 파일에 다음과 같이 의존성을 추가합니다.

dependencies {
    implementation 'io.springfox:springfox-swagger2:2.9.2'
    implementation 'io.springfox:springfox-swagger-ui:2.9.2'
}

Swagger 설정

Swagger를 사용하기 위해서는 @Configuration 어노테이션이 붙은 설정 파일을 작성해야 합니다. 다음은 Swagger 설정 파일의 예시입니다.

@Configuration
@EnableSwagger2
public class SwaggerConfig {
 
    @Bean
    public Docket api() { 
        return new Docket(DocumentationType.SWAGGER_2)  
          .select()                                  
          .apis(RequestHandlerSelectors.any())              
          .paths(PathSelectors.any())                          
          .build();                                           
    }
}

위 코드에서 @EnableSwagger2 어노테이션은 Swagger를 사용하도록 설정합니다. Docket은 Swagger API 문서를 생성하기 위한 빌더 클래스로, select() 메소드를 통해 API 문서를 생성할 때 필요한 정보를 설정합니다. apis() 메소드는 문서화할 API들을 선택하는데 사용되며, any() 메소드를 사용하면 모든 API를 선택할 수 있습니다. paths() 메소드는 문서화할 API 경로를 선택하는데 사용되며, any() 메소드를 사용하면 모든 경로를 선택할 수 있습니다.

 

Swagger 사용

Swagger 설정이 완료되면, http://localhost:8080/swagger-ui.html 주소로 접속하면 Swagger UI 페이지를 볼 수 있습니다. Swagger UI 페이지에서는 문서화된 API 목록과 해당 API의 사용 방법을 확인할 수 있습니다.

Swagger UI 페이지에서는 API 목록 중 하나를 선택하여 해당 API의 상세한 정보를 볼 수 있습니다. 해당 API의 매개변수, 반환값 등을 확인할 수 있으며, Swagger UI 페이지에서 해당 API를 실행할 수도 있습니다.

Swagger UI 페이지에서 API를 실행하면, API 실행 결과를 확인할 수 있습니다. 이를 통해, Swagger를 사용하여 API를 문서화하고 실행해보는 경험을 할 수 있습니다.

 

Swagger 주석

Swagger를 사용하여 API를 문서화하기 위해서는, Swagger 주석을 작성해야 합니다. Swagger 주석은 API 메소드의 주석으로 작성되며, Swagger 문서 생성 시 API의 정보를 정의합니다.

Swagger 주석의 예시는 다음과 같습니다.

@RestController
@RequestMapping("/api")
public class MyController {

    @ApiOperation(value = "API 설명", notes = "API 상세 설명")
    @ApiResponses(value = {
        @ApiResponse(code = 200, message = "성공"),
        @ApiResponse(code = 400, message = "잘못된 요청"),
        @ApiResponse(code = 500, message = "서버 오류")
    })
    @GetMapping("/my-api")
    public ResponseEntity<String> myApi(
            @ApiParam(value = "매개변수 설명") @RequestParam String myParam) {
        // API 구현
    }
}

위 코드에서 @ApiOperation 어노테이션은 API 메소드의 설명과 상세 설명을 정의합니다. @ApiResponses 어노테이션은 API의 응답 코드와 메시지를 정의합니다. @ApiParam 어노테이션은 API 매개변수의 설명을 정의합니다.

결론

Spring Framework에서 Swagger를 사용하여 API를 문서화하고 실행하는 방법에 대해 알아보았습니다. Swagger를 사용하면 API를 쉽게 문서화할 수 있으며, Swagger UI 페이지에서 API를 실행하여 결과를 확인할 수 있습니다. 또한, Swagger 주석을 사용하여 API의 정보를 정의할 수 있습니다. 이를 통해, Spring Framework에서 API 개발 및 문서화를 보다 쉽게 수행할 수 있습니다.