Swagger UI 사용하기

sieun·2022년 4월 6일

개요

실패담 공유 플랫폼인 서리담 프로젝트를 진행하면서 프론트팀에게 API문서를 공유하는 작업이 필요하였습니다. 이전 프로젝트에서는 github wiki에 API를 정리하였는데, API의 수정이 이루어질 때마다 문서를 변경해야 하는 점이 번거로웠습니다. 프로젝트가 커질수록 API 문서의 관리가 어렵고 귀찮아지기 때문에 Swagger UI라는 툴을 사용해보려고 합니다.

Swagger UI란

Swagger UI는 Swagger 서비스 중에서 API문서화 기능을 제공하는 제품입다.

Swagger UI를 사용하면 누구나 로직을 구현하지 않고도 API 리소스를 시각화하고 상호 작용할 수 있도록 도와줍니다. Swagger는 OpenAPI사양으로 자동 생성되며 문서를 시각적으로 제공하여 백엔드 구현 및 협업 과정에서 API소통을 편리하게 할 수 있게 합니다.

설정과정

build.gradle

// 의존성 추가
dependencies {
..
	implementation group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2'
	implementation group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'
..
}

SwaggerConfig.java

// 환경 설정 파일

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

application.yml

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

위의 설정들을 마치고 Controller클래스(및 dto클래스 등..)를 작성하여 진행하면 됩니다.

추가 옵션

// 해당 Api의 추가적인 정보를 작성
@ApiOperation(value="User 계정 생성", notes="User의 정보를 입력하여 계정을 생성한다.", response = SuccessResponse.class)

// dto객체의 속성의 요청 데이터 포맷 설명을 작성 (request)
@ApiParam(value = "회원 아이디", required = true, example = "1")
private String id;

// dto객체의 속성에 응답 데이터 포맷 설명을 작성 (response)
@ApiModelProperty(notes = "회원 고유 번호", example = "1")
private Long id;