[SpringBoot] 스웨거(Swagger)

Swagger

해당 API가 어떤 로직을 수행하는지 설명하고 이 로직을 수행하기 위해 어떤 값을 요청하며, 이에 따른 응답값으로는 무엇을 받을 수 있는지 정리한 오픈소스 프로젝트이다.

 

1. pom.xml 파일에 Swagger 의존성 추가

// Spring Boot 버전 2.6.x 상위버전용
<dependencies>
		...
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-boot-starter</artifactId>
			<version>3.0.0</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>3.0.0</version>
		</dependency>
</dependencies>

// Spring Boot 버전 2.6.x 하위버전용
<dependencies>
		...
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.9.2</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.9.2</version>
		</dependency>
</dependencies>

 

2. root 패키지 안에 config 패키지 생성 후 Swagger 설정 코드 작성

config/SwaggerConfiguration.java
// Spring Boot 2.6.x 상위
@EnableWebMvc
@Configuration

public class SwaggerConfiguration {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    public ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot Practice Rest API Documentation")
                .description("springboot rest api practice.")
                .version("0.1")
                .build();
    }
}

// Spring Boot 2.6.x 하위
@EnableWebMvc
@Configuration
public class SwaggerConfiguration {
	@Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("{루트패키지명}"))
                .paths(PathSelectors.any())
                .build();
    }

    public ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot Practice Rest API Documentation")
                .description("springboot rest api practice.")
                .version("1.0.0")
                .build();
    }
}

 

3. ApiApplication 실행 후 http://localhost:8080/swagger-ui/index.html

Swagger 화면

 

4. GetController 기존 코드에 Swagger 명세를 추가

• ApiOperation: 대상 API의 설명을 작성하기 위한 어노테이션
• ApiParam: 매개변수에 대한 설명 및 설정을 위한 어노테이션, 매서드의 매개변수뿐 아니라 DTO 객체를 매개변수로 사용할 경우 DTO 클래스 내의 매개변수에도 정의할 수 있다.

@RestController
@RequestMapping("/api/v1/get-api")
	public class GetController {
    	... 
        // http://localhost:8080/api/v1/get-api/request3?name=value1&email=value2&organization=value3
        @ApiOperation(value="GET 메서드 예제", notes = "@RequestParam을 활용한 GET Method")
        @GetMapping(value = "/request3")
        public String getRequestParam3(MemberDto memberDto) {
            // return memberDto.getName() + " " + memberDto.getEmail() + " " + memberDto.getOrganization();
            return memberDto.toString();
        }
        ...
}

 

5. Swagger 페이지에서 API 명세 확인

@ApiOperation에 작성한 내용은 그림 상단에 표기되고 @ApiParam에 정의한 내용은 아래 "Parameters"영역의 "Description" 항목에 추가되었다. 위와 같이 Swagger는 해당 API가 무엇인지 설명하고 어떤 값이 필요한지 보여준다. 

[Try it out] 버튼을 누르고 "Parameter"의 각 항목에 값을 기입하고 [Execute] 버튼을 누르면 결과값을 받을 수 있다.

 

 

 

참고 문헌: 스프링 부트 핵심 가이드(스프링 부트를 활용한 애플리케이션 개발 실무)

http://www.yes24.com/Product/Goods/110142898