[Spring Boot] 스프링 부트 프로젝트 Swagger 사용해보기-6 (@EnableSwagger2,@Configuration, @ApiOperation, @ApiParam)

권경환·2024년 1월 21일

@ApiOperation @EnableSwagger2 Configuration Spring Swagger apiparam api명세서 문서화 스프링부트

JAVA

목록 보기

6/13

스프링부트 핵심가이드 책을 참고하여 정리해보는 시간을 가져보려고 합니다!

Swagger란?

API를 개발하면 API의 URL, 요청 형식, 헤더, 에러코드 등 해당 API에 대한 정보를 일관된 형식으로 기술한 문서를 API 명세서라고 합니다.

API는 개발 과정에서 계속 변경되기에 작성한 명세서도 주기적으로 업데이트를 해주어야 하는데 해당 명세작업은 시간이 오래걸리기 때문에 해당 문제를 해결하기 위해 Swagger가 등장했습니다.
REST API를 편리하게 문서화 해주며 다른 사용자가 편리하게 API를 호출해보고 테스트 할 수 있는 프로젝트입니다!

Swagger를 제가 만들고 있는 Spring boot 프로젝트에 적용해보도록 하겠습니다.

Swagger 적용법

저는 Maven기반으로 개발하고 있어서 해당 기준으로 Swagger를 적용하는 순서들을 작성하겠습니다.

pom.xml 파일에 의존성을 추가합니다.

우리가 사용하고자하는 라이브러리를 pom.xml에 추가하면 Maven에서 자동으로 다운로드하여 프로젝트에 빌드해줍니다.

Swagger를 사용해볼것이기 때문에 pom.xml에 <dependencies> 안에 다음과 같이 추가해보도록 하겠습니다.

※ 참고

spring-boot-starter-parent version 2.6.2
springfox-swagger2, springfox-swagger-ui 모두 version 2.9.2를 사용하고 있습니다.

<dependencies>
	<dependency>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-test</artifactId>
		<scope>test</scope>
	</dependency>
	<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>

자동으로 문서화할 패키지 안에config 폴더를 만들고 SwaggerConfig.java를 생성합니다.

SwaggerConfig.java에 설정 코드를 작성합니다.

예제코드

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage
                ("com.springboot.study02"))
                .paths(PathSelectors.any())
                .build();
    }

    public ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("스프링 부트 Swagger 사용해보기!")
                .description("설명부분")
                .version("0.0.1")
                .build();
    }
}

@Configuration을 안에 @Bean을 이용하여야 싱글톤을 보장받을 수 있습니다.
Swagger2 버전을 활성화 하겠다는 어노테이션 @EnableSwagger2
Docket Swagger 설정의 핵심이며 문서화 객체입니다
ApiInfo에 title은 API명세서 제목이며, description은 설명 version은 업데이트할때마다 증가될 버전입니다.
RequestHandlerSelectors.basePackage(packageName)
Swagger를 적용할 클래스의 package 명을 적어줍니다.
PathSelectors.any()
해당 package 하위에 있는 모든 url에 적용시킵니다
설정코드를 작성하여 실행시키고 http://localhost:8080/swagger-ui.html 로 접속을 하면 아래와 같이 자동으로 문서화된 API들이 정리되어서 나옵니다

결과

기존 코드에 Swagger 명세 추가방법

아래와 같은 어노테이션을 사용하면 더욱더 자세하게 API 명세서를 작성할 수 있게 해줍니다.

@ApiOperation
대상 API의 설명을 적는 어노테이션
@ApiParam
매개변수 설정을 위한 어노테이션

위 어노테이션을 작성한 예제코드입니다.

예제코드

//GetController.java
@RestController
@RequestMapping("/api")
public class GetController {
    @ApiOperation(value="GET 메소드 예제",
    notes="@getVariable을 활용한 GET 메소드입니다.")
    @GetMapping(value = "/get")
    public String getVariable(
    @ApiParam(value="이름",required = true) 
    @RequestParam String name,
    @ApiParam(value="나이",required = true)
    @RequestParam String age) {
        return "Name: " + name +", Age: " + age;    
    }
}