Spring boot에 Swagger 적용하기

개요

 API 인터페이스 관리는 스펙이 변할때 마다 일일이 수정하게 되면 생각보다 많은 비용이 드는데 Swagger를 이용하면 불필요한 비용을 줄일 수 있도록 API 문서화를 도와 단순하게 관리할 수 있다. 여기서 Swagge란, OAS(Open Api Specification)를 위한 프레임워크로 API 문서 자동화 및 테스트 기능이 있다.

 

Swagger 적용 방법

우리는 많이 사용되는 Springfox를 이용해 swagger를 적용할 것이다.

프로젝트 버전

• java : 11
• spring-boot : 2.7.9
• springfox-swagger : 3.0.0

1. 의존성 추가

dependencies{
	implementation 'io.springfox:springfox-boot-starter:3.0.0'
	implementation 'io.springfox:springfox-swagger-ui:3.0.0'
}

 

2. SwaggerConfiguration 클래스 생성 (설정 파일 역)

• @Configuration 어노테이션으로 설정 파일임을 명시한다.
• Docket bean을 이용하여 명세에 필요한 내용들을 설정해준다.

@Configuration
public class SwaggerConfiguration {
    @Bean
    public Docket api(){
        return new Docket(DocumentationType.OAS_30)
                .useDefaultResponseMessages(false)
                .select()
                .apis(RequestHandlerSelectors.basePackage("suso.backend.api.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("Suso API Document")
                .description("This is Suso API Document")
                .version("1.0")
                .build();
    }

}

 

      Docket의 select 메서드를 통해 aApiSelectorBuilder를 생성

Docket의 select 메서드를 통해 ApiSelectorBuiler를 반환한다.

 

      ApiSelectorBuilder의 apis, paths, apiInfo 메서드 등을 이용해 설정

ApiSelectorBuilder 클래스

      ApiInfo 생성자에서 swagger-ui의 메인화면 정보들을 설정해준다.

ApiInfo 생성자

 

3. Swagger 설정이 끝났으면 다음 어노테이션으로 각 API에 대한 명세를 추가한다.

• @Api : 컨트롤러 이름을 설정

@Api(tags = "수료증 api")
@RestController
@RequiredArgsConstructor
public class CertificatesController {
	...
}

• @ApiOperation(value="사용목적", notes="설명") : 매핑된 API URL에 대한 명세
• @ApiParam : 매핑된 API의 파라미터 값을 명세
• @ApiResponse(code="코드", message="상태 메세지") : response에 대한 명세

    @GetMapping(ApiUrl.CERTIFICATES)
    @ApiResponse(code=200, message="성공")
    @ApiOperation(value = "수료증 전체 조회 API")
    public List<CertificatesResponse> getCertificates(@ApiParam(value="유저 ID", required = true) @RequestParam Long id){
        return certificatesService.findAllByUserId(id);
    }

 

• @ApiModel(value="설명") : schema에 있는 model에 대한 명세

@Data
@Builder
@ApiModel(value = "Certificates 정보")
public class CertificatesResponse {
    private Long id;
    private String title;
    
    ...

}

 

결과

 Swagger 설정이 끝났으면 http://{{주소}}/swagger-ui/index.html로 접속하여 확인하자.

swagger-ui 접속화면

 

 

참고 자료

• Springfox 문서 : https://github.com/springfox/springfox
• Swagger 적용 : https://chanos.tistory.com/entry/Spring-API-%EB%AC%B8%EC%84%9C-%EC%9E%90%EB%8F%99%ED%99%94%EB%A5%BC-%EC%9C%84%ED%95%9C-Swagger-300-%EC%A0%81%EC%9A%A9
• Swagger 기본 설정 : https://velog.io/@kijrary/Spring-Boot-%ED%94%84%EB%A1%9C%EC%A0%9D%ED%8A%B8Gradle-%EC%97%90%EC%84%9C%EC%9D%98-Swagger-3.0.0-%EC%84%A4%EC%A0%95-%EB%B0%A9%EB%B2%95
  
  

감사합니다.