Spring Boot Swagger 사용법

오성민·2022년 11월 22일
0

spring

목록 보기
7/17
post-thumbnail

현재 프로젝트를 진행하면서 굉장한 문제를 만났다.

그건 바로 Backend 작업을 마무리하고 Frontend 작업을 할 때 API 목록과 해당 URL, 파라미터 등 정보를 계속해서 까먹어서 다시 찾아봐야하는 문제였다.

이러한 문제를 초반에 해결하기 위해서 notion을 사용해서 api 리스트를 정리하고 시작을 하였지만, 귀찮아서(?) 업데이트를 하지 않다보니 지금 하는 것과는 많이 달라져있었다.

이런 작업을 보다 편리하게 하는 방법을 찾던 중 swagger를 발견하였고, 해당 기능을 사용하여서 API 리스트를 자동화하여 정리하였다.

swagger

swagger는 Backend가 개발한 API List, Model 을 자동으로 정리하여 볼 수 있게 해주는 기능이다.
이 기능을 사용하면 좋은 점으로는

  • Frontend가 개발을 진행할 참고할 수 있는 문서를 큰 힘을 들이지 않고 만들 수 있음.
  • 해당 서버를 이용해서 페이지를 보여주는 것이기 때문에, list를 보여주기 위해서 서버를 더 유지할 필요가 없음.
  • Backend 입장에서 postman을 사용하지 않더라도 간단한 api 테스트를 할 수 있음.

dependency

  • Gradle

//swagger UI
implementation group: 'io.springfox', name: 'springfox-boot-starter', version: '3.0.0'
implementation group: 'io.springfox', name: 'springfox-swagger-ui', version: '3.0.0'

나는 현재 프로젝트를 gradle 환경에서 진행하고 있기 때문에 위와 같이 build.gradle에 추가하여서 의존성을 추가해주었다.

Config

@Configuration
@EnableWebMvc
public class SwaggerConfig {

    private ApiInfo swaggerInfo() {
        return new ApiInfoBuilder().title("Community API")
                .description("Community API Docs").build();
    }

    @Bean
    public Docket swaggerApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .consumes(getConsumeContentTypes())
                .produces(getProduceContentTypes())
                .apiInfo(swaggerInfo()).select()
                .apis(RequestHandlerSelectors.basePackage("com.example.community.controller"))
                .paths(PathSelectors.any())
                .build()
                .useDefaultResponseMessages(false);
    }

    private Set<String> getConsumeContentTypes() {
        Set<String> consumes = new HashSet<>();
        consumes.add("application/json;charset=UTF-8");
        consumes.add("application/x-www-form-urlencoded");
        return consumes;
    }

    private Set<String> getProduceContentTypes() {
        Set<String> produces = new HashSet<>();
        produces.add("application/json;charset=UTF-8");
        return produces;
    }
}

위와 같이 추가를 하여 구성하였다.

@Configuration

해당 어노테이션을 사용해야지 bean으로 등록이 된다. 그리고 가독성을 위해서 반드시 설정 클래스에만 해당 어노테이션을 사용한다.

@EnableWebMvc

해당 어노테이션을 사용해야지 spring에 여러 설정값을 등록할 수 있다.

method

  • swaggerInfo() : 해당 swagger에 제목과 설명을 작성한다.

  • swaggerApi() : 여러 설정을 한다.

  • apis() : 어떤 package에 들어있는 api를 문서화할지를 설정해준다.

  • apiInfo() : swagger api 문서에 대한 설명을 표기하는 메소드

  • path() : 해당 경로로 들어오는 api만 문서화한다.

  • getConsumeContentTypes() : request content type을 설정해줌

  • getProduceContentTypes() : response content type을 설정해줌.

@ApiOperation

api method에 이름을 달고, 설명을 붙일 수 있는 어노테이션이다.

@ApiParam

api dto에 이름을 달고, 설명을 붙일 수 있음.

@Api

해당 클래스에 존재하는 api method의 대분류 이름을 설정할 수 있음

redirector

해당 클래스를 만들어서 좀 더 직관적으로 알 수 있게 구성을 하였다.

테스트 모습

이렇게 잘 나온다.
보다 더 보기 좋고 깔끔하게 정리해야겠다.

profile
풀스택을 지향하는 개발자

0개의 댓글