SpringBoot에 Swagger을 빠르게 적용해보기

Swagger

요즘 백엔드 개발은 ModelAndView 방식보다는 API 위주의 어플리케이션을 권장하고 있다. API 개발이 많아짐에 따라, 프로젝트 안의 API를 관리할 수 있는 문서가 필요해졌다. API 문서를 만들기 위해서 Swagger을 프로젝트 안에 Setting 하여 사용해보자. Swagger에는 많은 기능들이 담겨져있다. 우리는 Swagger을 사용하여 어노테이션을 통해 그 많은 기능들을 사용할 수 있다.

 

 

Swagger + SpringBoot 연동

1. build.gradle 에 의존성 추가

//swagger
compile "io.springfox:springfox-swagger2:2.9.2"
compile "io.springfox:springfox-swagger-ui:2.9.2"

 

 

2. WebConfig.java 파일에 코드 추가

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

위 코드를 추가하지않으면, url/swagger-ui.html 호출시 개발자도구의 Network 탭으로 확인해보면 리소스 파일들을 가져오지못함을 알 수 있다.

 

3. SwaggerConfig.java 생성

@Configuration
@EnableSwagger2
@ComponentScan(basePackages={
        "com.test.technology.controllers"
})
public class SwaggerConfig {
    /** swagger */
    @Bean
    public Docket AdminApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("Test API")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.test.technology.controllers"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(this.TestApiInfo())
                .tags(new Tag("RedisController", "Redis API")
                        , new Tag("ElasticController", "ElasticSearch API")
                        , new Tag("DeptController", "JPA+Oracle DB 연동 API")
                        , new Tag("TestController", "TEST API")
                        , new Tag("FeignController", "TEST API")
                    );

    }

    private ApiInfo TestApiInfo() {
        return new ApiInfoBuilder()
                .title("Test API")
                .description("technology API")
                .termsOfServiceUrl("http://www.seohae-technology.com")
                .version("1.0")
                .build();
    }
}

위 코드들을 간단하게 분석해보자.

 

코드	설명
groupName	graupName 지정
apis	패키지를 지정할 수 있고, 또는 Controller.java 파일 안의 메소드마다 사용할 수 있는 어노테이션인 @ApiOperation(value = “test”) 가 적재된 api만 Swagger에 노출할 수 있도록 설정할 수 있다.
paths	apis에 해당하는 패키지의 모든 path에 해당하는 api를 Swagger에 노출한다. 또는, 다른 설정으로 특정한 url만 Swagger 노출이 가능하다.
apiInfo	아래 TestApiInfo method에 정의된 정보들을 swagger 페이지에 보여준다
tags	Controller.java 파일에 @Api 어노테이션 사용시, 사용하기위함 ex) @Api(tags = {“TestController”})

 

4. Swagger Annotation의 사용

@Api(tags = {"RedisController"})
@RestController
@RequestMapping("/redis")
public class RedisController {

    private final RedisTemplate<String, String> redisTemplate;

    public RedisController(RedisTemplate<String, String> redisTemplate) {
        this.redisTemplate = redisTemplate;
    }

    @ApiOperation(value = "redis key 등록")
    @PostMapping("")
    public ResponseEntity<?> addRedisKey(@ApiParam(value = "key", defaultValue = "") @RequestParam String) {
        ...
    }
}

2개의 어노테이션을 보자.

 

@Api : Controller 클래스명 위에 위치
@ApiOperation : Method 명 위에 위치 / 각 api 마다 설명
@ApiParam : 파라미터 어노테이션(@RequestParam, @RequestBody 등) 앞에 위치 / 각 파라미터 설명

 

 

마무리

Swagger 설정이 완료되었다면 접속해보자.
Swagger 접속은 url/swagger-ui.html 으로, url 뒤에 /swagger-ui.html을 붙혀주면 접속이 가능하다.

 

ex) localhost:8080/swagger-ui.html