[Spring] Swagger 👋

홍준·2022년 1월 10일

들어가며

이번에 1인 토이 프로젝트를 진행 해보려고 한다.
백엔드는 REST API 설계 및 문서화 등에 유용하게 사용되는 Swagger를 이용하여 만들어보려고 한다.

스웨거(Swagger) 는 Open Api Specification(OAS)를 위한 프레임워크이다.
즉, 간단히 말해 API 스펙을 명세, 관리할 수 있는 프로젝트/문서라고 정의할 수 있다.

선택이유

진행하려는 토이프로젝트는 개인 프로젝트이다 보니 디자인도 깔끔하게 안 나오고, 문서화에 시간을 많이 쓰고 싶지 않았다.이렇게 귀찮은 일은 자동화 시키는 게 훌륭한 방법이라고 생각하는데 이를 위한 라이브러리가 Swagger라 생각들어 사용하게 되었다.

Swagger 장점

적용하기 쉽다.
API 정보 현황화 가능하다.
테스트할 수 있는 UI를 제공한다.

아키텍처

Swagger 사용법

1. Swagger 의존성 추가

Swagger 사용을 위해 pom.xml에 해당 의존성 추가 해야한다.

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

2. config 세팅

swagger 설정을 위해 SwaggerConfig 클래스를 생성한다.

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

	  private ArrayList<ResponseMessage> getArrayList() {
	        ArrayList<ResponseMessage> lists = new ArrayList<ResponseMessage>();
	        lists.add(new ResponseMessageBuilder().code(500).message("500Error").build());
	        lists.add(new ResponseMessageBuilder().code(403).message("403Error").build());
	        lists.add(new ResponseMessageBuilder().code(401).message("401rror").build());
	        return lists;
	    }
	  
	  
	   public ApiInfo getApiInfo() {
	        return new ApiInfo(
	        	"Service REST API Documentation",        
	                "REST Api Documentation",            
	                "1.0",                              
	                "localhost:8080",
	                new Contact("hongjun","","hongjun@velog.com"), 
	                "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0",
	                new ArrayList<VendorExtension>());
	    }

}

@EnableSwagger2
Docket

useDefaultResponseMessages()
false로 설정하면, swagger에서 제공해주는 응답코드 (200,401,403,404)에 대한 기본 메시지를 제거해준다.
select()
ApiSelectorBuilder를 생성하여 apis()와 paths()를 사용할 수 있게 해준다.
apiInfo()
제목, 설명 등 문서에 대한 정보들을 설정하기 위해 호출한다.
apis()
api 스펙이 작성되어 있는 패키지를 지정한다.
paths()
apis()로 선택되어진 API중 특정 path 조건에 맞는 API들을 다시 필터링하여 문서화한다.
PathSelectors.any()로 설정하면 패키지 안에 모든 API를 한 번에 볼 수 있다.

💡 자세한 Docket Bean을 설정 방법 및 설명은 여기를 참고하면 된다.

3. Controller 설정


import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.HashMap;
import java.util.Map;

@Api(value = "SwaggerController")
@RequestMapping("/v1/api")
@RestController
public class SwaggerController {

    @ApiOperation(value = "this is test!", notes = "note!!!!!")
    @GetMapping(value = "/board")
    public Map<String, String> selectOneBoard(@ApiParam(name = "first param", value = "first value", required = true) String input) {
        Map<String, String> result = new HashMap<>();
        result.put("author", "hongjun");
        result.put("content", "V1 API 내용");
        return result;
    }
	
}