Spring Boot에 Swagger 적용하기



 

Swagger

- REST API 개발 시 문서를 자동으로 만들어주는 프레임워크

(*REST API: 웹에 존재하는 자원에 고유한 URI를 부여해 외부에서 플랫폼이나 언어와는 독립적으로 활용 가능한 인터페이스)

- 간단한 설정으로 프로젝트에 지정한 URL들을 HTML 화면으로 확인

- API에 대한 매뉴얼 자동 생성

- Postman과 같이 API 테스트 가능

- Java, Python, Node.js 등 다양한 언어를 지원한다.

---

Spring Boot에 Swagger 적용하기

---

 

1. 라이브러리 추가

Maven Project일 경우 pom.xml에 추가

<!-- Swagger -->
<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>

Gradle Project일 경우

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

---

2. SwaggerConfig.java 파일 생성

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

여기까지 하고 실행 후 http://localhost:8080/swagger-ui.html#/ 로 접속해보면 API 문서가 생성된 것을 확인할 수 있다.

---

3. @ApiOperation Annotation으로 메서드에 대한 설명 추가

(*Annotation: @를 이용한 주석으로, 자바코드에 주석을 달아 특별한 의미를 부여한 것)

@ApiOperation(value = "로그인", notes = "성공시 jwt 토큰을 헤더에 넣어서 반환합니다.")

해당 Controller의 메소드에 이렇게 Annotation을 추가하고 나면 

Before

After

Swagger에서 해당 URI의 메소드에 대한 설명이 추가된다.

---

4. @ApiImplicitParams Annotation으로 RequestDto 파라미터에 대한 설명 추가

@ApiImplicitParams({
	@ApiImplicitParam(name = "name", value = "이름", required = true),
	@ApiImplicitParam(name = "part", value = "파트", required = true, dataType = "string", paramType = "query", defaultValue = "서버"),
	@ApiImplicitParam(name = "password", value = "비밀번호", required = true, dataType = "string", paramType = "query")
})

해당 Contorller의 메소드에 이렇게 Annotation을 추가하고 나면

(dataType과 paramType은 해당 name의 정보가 자동으로 채워지기 때문에 생략해도 된다.

만약 명시하고 싶을 시 parameterType에는 @RequestParam일 경우 "query", @PathVariable일 경우 "path"를 적어주면 된다.)

Before

After

필수 값인지에 대한 여부, 해당 파라미터에 대한 설명와 Default 값이 추가된다.

---

5. @ApiResponses Annotation으로 응답에 대한 설명 추가

@ApiResponses({
	@ApiResponse(code = 200, message = "로그인 성공"),
	@ApiResponse(code = 400, message = "잘못된 접근"),
	@ApiResponse(code = 500, message = "서버 에러")
})

해당 Contorller의 메소드에 이렇게 Annotation을 추가하고 나면

이렇게 해당 응답 코드에 대한 설명이 추가된다.

해당 메소드에서 사용하지 않지만 디폴트로 나오는 응답 코드들을 삭제하려면 SwaggerConfig.java 파일에 한 줄만 추가하면 된다.

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .useDefaultResponseMessages(false)	//추가
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
}​

상태 코드 참고

---

6. @ApiModelProperty Annotation으로 해당 파라미터에 대한 example 값 추가

@Data
public class LoginReq {
    @ApiModelProperty(example = "신혜란")
    private String name;
    @ApiModelProperty(example = "hyeran")
    private String password;
}

해당 Req/Dto의 필드에 이렇게 Annotation을 추가하고 나면

Before

After

이렇게 Example Value에 각 파라미터들에 대한 example 값이 추가된다.

---

7. Swagger UI 페이지에 보여지는 API 정보 커스텀하기

SwaggerConfig.java 파일에 ApiInfo 메서드 추가

@SuppressWarnings("deprecation")
private ApiInfo apiInfo() {
	ApiInfo apiInfo = new ApiInfo(
            "Title",
            "Description",
            "Version",
            "Terms of Service URL",
            "contact Name",
            "License",
            "License URL"
    );
    return apiInfo;
 }

 

Before

After

---

SwaggerConfig.java 파일을 중간 중간 수정했는데 결과적으로 이렇게 작성하면 된다.

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .useDefaultResponseMessages(false)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())	//기본 패키지 설정(any, none, base package, class annotation, method annotations
                .paths(PathSelectors.ant("/api/**"))	//노출할 API 경로 패턴 설정(any, none, regex, ant)
                .build();
    }

    //Swagger UI 페이지에 노출할 내용 커스텀
    @SuppressWarnings("deprecation")
    private ApiInfo apiInfo() {
        ApiInfo apiInfo = new ApiInfo(
                "Title",
                "Description",
                "Version",
                "Terms of Service URL",
                "contact Name",
                "License",
                "License URL"
        );
        return apiInfo;
    }
}