[Spring] 스웨거(Swagger) 설정

 

 

 

 

 

매번 Thymeleaf, Jsp, Pebble, Freemarker 등등 템플릿 엔진만 사용하다 보니 퍼블리싱 작업본을 받아서 사용자 화면을 완성하는 작업을 주로 하게 됐었는데, 이번에는 새롭게 JPA와 React 또는 Vue를 사용하여 Back / Front를 명확하게 분리하고 Back 쪽에서는 Front 쪽으로 API 규격서만 전달하려고 합니다.

 

이때, 사이드 프로젝트로 진행하다 보니까 시간적 여유가 많지가 않아서 API 연동규격서까지 작성하기에는 어려움이 있었습니다. (핑계인거 다들 아시죠?)

 

해서.. 이번 기회에 스웨거(Swagger) API를 활용해서 API 연동규격서는 Swagger에게 맡겨보려고 합니다.

 

 

---

#1. Swagger 설정

 

1. gradle 설정

// swagger
implementation 'io.springfox:springfox-boot-starter:3.0.0'
implementation 'io.springfox:springfox-swagger-ui:3.0.0'

 

2. maven 설정

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.9.2</version>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.9.2</version>
</dependency>

 

3. SwaggerConfig.java 자바파일 생성 및 설정

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
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;

import java.util.HashSet;
import java.util.Set;

/**
 * 스웨거 설정
 * @ApiIgnore 를 통해서 제외 가능
 */
@Configuration
@EnableWebMvc
public class SwaggerConfig {

    private ApiInfo swaggerInfo() {
        return new ApiInfoBuilder()
                .title("SAMPLE API")
                .description("SAMPLE API Docs")
                .version("1.0")
                .build();
    }

    @Bean
    public Docket swaggerApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .consumes(getConsumeContentTypes())
                .produces(getProduceContentTypes())
                .apiInfo(swaggerInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("kr.co.sample"))
                .paths(PathSelectors.any())
                .build()
                .useDefaultResponseMessages(false);
    }

    private Set<String> getConsumeContentTypes() {
        Set<String> consumes = new HashSet<>();
        consumes.add("application/json;charset=UTF-8");
        consumes.add("application/x-www-form-urlencoded");
        return consumes;
    }

    private Set<String> getProduceContentTypes() {
        Set<String> produces = new HashSet<>();
        produces.add("application/json;charset=UTF-8");
        return produces;
    }
}

• .apis()는 Swagger API 문서로 만들기 원하는 BasePackage 경로. (필수)
• .path()는 URL 경로를 지정하여 해당 URL에 해당하는 요청만 Swagger API 문서로 만든다. (필수)
• .apiInfo()는 Swagger API 문서에 대한 설명을 표기하는 메소드. (선택)
• .consume()과 .produces()는 각각 Request Content-Type, Response Content-Type에 대한 설정. (선택)

300x250

 

---

#2. Swagger Annotations 종류

 

1. @ApiOperation

@ApiOperation(
    value = "사용자 정보 조회"
    , notes = "사용자의 ID를 통해 사용자의 정보를 조회한다."
)

• 메소드 설명 어노테이션

 

 

2. @ApiImplicitParam

//단일
@ApiImplicitParam(
	name = "id"
	, value = "사용자 아이디"
	, required = true
	, dataType = "string"
	, paramType = "path"
	, defaultValue = "None"
)

//복수개
@ApiImplicitParams({
	@ApiImplicitParam(
		name = "id"
		, value = "자격증 아이디"
		, required = true
		, dataType = "string"
		, paramType = "path"
		, defaultValue = "None"
	),
	@ApiImplicitParam(
		name = "fields"
		, value = "응답 필드 종류"
		, required = false
		, dataType = "string"
		, paramType = "query"
		, defaultValue = ""
	)
})

• Request Parameter 설명 어노테이션
• dataType, paramType, required의 경우 해당 name의 정보가 자동으로 채워지므로 생략 가능
• @ApiImplictParams로 @ApiImplictParam을 복수개 사용 가능

 

 

3. @ApiResponse

//단일
@ApiResponse(
	code = 200
	, message = "성공입니다."
)

//복수개
@ApiResponses({
	@ApiResponse(code = 200, message = "성공입니다.")
	, @ApiResponse(code = 400, message = "접근이 올바르지 않습니다.")
})

• Response 설명 어노테이션
• useDefaultResponseMessages(false)를 SwaggerConfig.java에 설정해 주면, @ApiResponse로 설명하지 않은 401, 403, 404 응답들이 사라짐

 

 

4. @ApiParam

@ApiParam(value = "사용자 ID", required = true)

• Dto Field 설명
• @ApiParam Annotation으로 DTO의 field에 대한 설명 추가 가능

 

 

5. @ApiModelProperty

@ApiModelProperty(
	name = "id"
	, example = "example1"
)

• Dto Field 예제 설명
• @ApiModelProperty Annotation을 사용하는 DTO Class Field에 추가하면, 해당 DTO Field의 예제 Data 추가 가능

 

 

6. @ApiIgnore

@ApiIgnore

• Swagger UI 상 무시 (제외)