API 자동화 툴 Swagger

Swagger란 ?

REST API를 설계, 빌드, 문서화 및 사용하는데 도움이되는 OpenAPI 스펙을 중심으로 구축이 된 오픈 소스 도구 세트이다.

쉽게 잘하면 API 문서 작성을 자동화 해주는 툴이라고 이해해도 좋다.

기존에 사용하던 Spring Rest Docs 와는 달리 Swagger는 몇 가지 어노테이션과 코드를 추가하면 자동으로 API를 문서화 해준다는 점에서 매우 유용하다.

사용법 - 코드 작성

의존성 추가
build.gradle -> dependencies

compile 'io.springfox:springfox-swagger2:2.9.2'
compile 'io.springfox:springfox-swagger-ui:2.9.2'

Configuration 파일 추가
SwaggerConfig.class

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

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

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("E1I3-Hand-Talk-Project")
                .description("Yolo 기반 수어 인식 웹 플랫폼 API 자동화 문서")
                .version("1.0")
                .build();
    }

    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger-ui/**").addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/");
    }
}

테스트용 컨트롤러 작성

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.http.ResponseEntity;

@RestController
@Tag(name = "UserController", description = "사용자 관련 API")
public class UserController {
    @Operation(summary = "user hello", description = "swagger example")
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "OK!!"),
            @ApiResponse(responseCode = "400", description = "BAD REQUEST !!"),
            @ApiResponse(responseCode = "404", description = "NOT FOUND !!"),
            @ApiResponse(responseCode = "500", description = "INTERNAL SERVER ERROR !!")
    })
    @GetMapping("/hello")
    public ResponseEntity<String> hello(@Parameter(description = "사용자 이름", required = true) @RequestParam String name) {
        
        return ResponseEntity.ok("hello " + name);
    }

사용법 - 작성된 문서 확인

모두 작성이 완료 되었다면 서버를 실행 시킨 뒤,http://localhost:8080/swagger-ui.html 로 들어가보면 작성된 내용들을 확인할 수 있다.

자세한 Swagger 사용법은 아래 링크 참고.
https://www.baeldung.com/swagger-2-documentation-for-spring-rest-api

[참고]

• https://c-king.tistory.com/537
• https://velog.io/@banjjoknim/Swagger
• https://haddoddo.tistory.com/entry/Spring-Boot-STS-%EC%8A%A4%ED%94%84%EB%A7%81%EB%B6%80%ED%8A%B8%EC%97%90-swagger-%EC%97%B0%EB%8F%99-%EB%B0%8F-%EC%82%AC%EC%9A%A9%EB%B2%95