Swagger2 사용하여 RESTful API 문서 자동화하기 (Feat.egovframework 전자정부프레임워크)

Swagger란?

개발한 API를 사용자에게 제공하도록  하는 Web API 문서화 도구로 쓰입니다.

Swagger를 사용하면, @어노테이션과 코드 설정을 통해 간단하게 API를 문서화 및 테스트가 가능한 UI를 제공하여

별도의 문서를 만들 필요 없이 Restful서비스의 문서작성과 유지보수에 대한 효율성을 높일 수 있습니다.

전자정부프레임워크(egovframework)에서 Swagger 적용하기

구글링을해보면 전부 스프링부트에서 Swagger를 적용하는 방법이어서,

전자정부를 사용하는 저는 Swagger를 구현하는데 많은 난관이 있었습니다.

 

그럼, 전자정부프레임워크에서 적용하는 방법을 알아보겠습니다.

1. pom.xml에 Maven dependency 추가

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

2. egov-com-servlet.xml 설정

<!-- Swagger 관련 설정 -->
<bean id="swaggerConfig" class="egovframework.com.cmm.config.SwaggerConfig"/>

<mvc:resources location="classpath:/META-INF/resources/" mapping="swagger-ui.html"/>
<mvc:resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**"/>

<!-- annotation-driven 설정 -->
<mvc:annotation-driven />

<mvc:default-servlet-handler />

3. SwaggerConfig.java 작성

- @EnableSwagger2 어노테이션을 반드시 추가하여야 합니다.

- host: api의 서비스 url이 다를 경우 설정 ex) host(182.0.0.1:80)

- useDefaultResponseMessages : 기본적 반환 Message 설정

- globalResponseMessage : 전반적 반환 Message 설정

- apis

• RequestHandlerSelectors.any() : 모든 URL 사용
• RequestHandlerSelectors.none() : 미사용
• RequestHandlerSelectors.basePackage("egovframework.common.web") : egovframework.common.web 패키지 내의 RequestMapping으로 할당된 모든 URL
• Predicates.not(RequestHandlerSelectors.basePackage("egovframework.common.web")) : egovframework.common.web 패키지 제외

- paths: PathSelectors 를 이용하여 path 에 대한 설정 가능

• PathSelectors.ant("/api/**"): api/** 인 URL들만 필터링
• PathSelectors.any(): 모든 URL 사용

- apiInfo() : swagger 상단 영역에 보이는 API 정보

- Status값 표시

 

SwaggerConfig.java

package egovframework.com.cmm.config;

import java.util.ArrayList;
import java.util.List;

import org.springframework.context.annotation.Bean;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.ResponseMessageBuilder;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.service.ResponseMessage;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@EnableSwagger2
@EnableWebMvc
public class SwaggerConfig {

    @Bean
    public Docket customImplementation() {
        return new Docket(DocumentationType.SWAGGER_2)
//            .host("xx.xx.x.xxx:80")          // 서비스 url 주소 설정
            .groupName("그룹명")
            .useDefaultResponseMessages(false)  // 기본적인 응답메시지 미사용
            .globalResponseMessage(RequestMethod.POST, getArrayList()) // 정의한 응답메시지 사용
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.any()) // .basePackage("egovframework.common.web")
            .paths(PathSelectors.ant("/api/**")) // .any()
            .build();
    }
    ParameterBuilder parameterBuilder = new ParameterBuilder();
    List<Parameter> parameters = new ArrayList<>();

    // Swagger UI에서 보여지는 정보
    private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
		.title("Rest Api 연계서비스")
		.description(" Rest Api 가이드 문서입니다.")
		.version("1.0.0")
		.termsOfServiceUrl("") 
		.license("") 
        .licenseUrl("") 
		.build();
	}
    
    private ArrayList<ResponseMessage> getArrayList() {
        ArrayList<ResponseMessage> lists = new ArrayList<ResponseMessage>();
        lists.add(new ResponseMessageBuilder().code(500).message("Internal Server Error").build());
        lists.add(new ResponseMessageBuilder().code(404).message("Not Found").build());
        lists.add(new ResponseMessageBuilder().code(403).message("403 ERROR").build());
        lists.add(new ResponseMessageBuilder().code(401).message("401 ERROR").build());
        return lists;
    }
    

}

4. RestController.java 작성

ApiOperation

- 각 API에 대한 설명을 @어노테이션을 사용하여 커스터마이징할 수 있습니다.

 

@Api
: Api가 어떤 역할을 하는 지 표시하는 어노테이션으로 컨트롤러 상단에 추가합니다.

• tags : Swagger UI에 보일 컨트롤러의 Title명칭 부여
• description : 컨트롤러 옆에 보일 간단한 정보

@Api(tags = {"01. API Info"}, description = "API 서비스 예시")

@ApiIgnore
: 특정 API를 제외하고 싶을 때 사용

@ApiOperation

: 각각의 method에 대한 제목과 설명 등의 정보를 표시

@ApiOperation(value = "회원 데이터 조회", notes = "회원 데이터를 조회한다")

• value : API에 대한 정보를 요약하여 작성
• notes : API에 대한 자세한 정보 작성
  

CommonRestController.java

import java.util.List;
import java.util.Map;

import javax.annotation.Resource;

import org.springframework.web.bind.annotation.CrossOrigin;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import egovframework.table.dto.MemberDTO;
import egovframework.table.dto.MemberDTO;
import egovframework.table.service.mbrService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;

@Api(tags = {"01. API Info"}, description = "API 서비스 예시")
@RestController
@CrossOrigin(origins="*")
@RequestMapping("/api")
public class CommonRestController {

	@Resource(name = "mbrService")
	private MbrService mbrService;
	
	@ApiOperation(value = "회원 데이터 조회", notes = "회원 데이터를 조회한다")
	@GetMapping("/member")
	public List<Map<String, Object>> selectMemberInfo(@RequestBody MemberDTO reqDto) throws Exception {
		List<Map<String, Object>> returnJson = mbrService.selectMemberInfo(reqDto);
		return returnJson;
	}
	
	@ApiOperation(value = "회원 데이터 조회 - DTO 객체 사용", notes = "회원 데이터를 조회한다.")
	@PostMapping("/member/dto")
	public List<Map<String, Object>> selectMemberInfoDto(@RequestBody MemberDTO reqDto) throws Exception {
		List<Map<String, Object>> returnJson = mbrService.selectMemberInfoDto(reqDto);
		return returnJson;
	}

	@ApiOperation(value = "회원 데이터 추가", notes = "회원 데이터를 추가한다")
	@PostMapping(value="/member/new")
	public List<Map<String, Object>> insertMemberInfo(@RequestBody MemberDTO reqDto) throws Exception {
		List<Map<String, Object>> returnJson = mbrService.insertMemberInfo(reqDto);
		return returnJson;
	}

	@ApiOperation(value = "회원 데이터 수정", notes = "회원 데이터를 수정한다")
	@PutMapping(value="/member/{mbr_id}")
	public List<Map<String, Object>> updateMemberInfo(@RequestBody MemberDTO reqDto) throws Exception {
		List<Map<String, Object>> returnJson = mbrService.updateMemberInfo(reqDto);
		return returnJson;
	}

	@ApiOperation(value = "회원 데이터 삭제", notes = "회원 데이터를 삭제한다")
	@DeleteMapping("/member/{mbr_id}")
	public List<Map<String, Object>> deleteMemberInfo(@RequestBody MemberDTO reqDto) throws Exception {
		List<Map<String, Object>> returnJson = mbrService.deleteMemberInfo(reqDto);
		return returnJson;
	}
}

5. 모델 추가하기

DTO 객체를 사용하여 Example Value에 예제를 추가할 수 있습니다.

@ApiModel

• value:  모델에 대한 설명
• description: 모델에 대한 상세 설명

@ApiModelProperty

• value:  속성에 대한 설명
• example: 속성의 default 값 또는 예시
• position: Swagger 문서에서 보이는 순서
• required: 속성의 필수여부 표기. 필수는 true, 아니면 false.

MemberDTO.java

import com.fasterxml.jackson.annotation.JsonProperty;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(value="MemberDTO : 회원 조회 파라미터", description="회원 조회에 필요한 데이터를 입력하세요.")
public class MemberDTO {
	
	@ApiModelProperty(value = "조회년월", position = 2, example="202204", required = true)
	@JsonProperty("PROC_YM")
	private String PROC_YM;
	
	@ApiModelProperty(value = "나이", position = 1, example="10", required = true)
	@JsonProperty("AGE")
	private String AGE;
	
	@ApiModelProperty(value = "삭제여부", position = 3, example="N", required = false)
	@JsonProperty("DEL_YN")
	private String DEL_YN;
	
}

Swagger 하단의 Models에서 DTO에 대한 정보를 확인할 수 있습니다.

Models

6. Swagger UI

Swagger UI 란,
api-docs url의 API data를 UI로 확인할 수 있는 내장 솔루션입니다.

 

서버를 실행 후 'http://localhost:8080/swagger-ui.html'로 접속하면 기본적인 Swagger가 동작하게 됩니다.
아래와 같이 정상적으로 자신이 추가한 Controller 정보가 나온다면 설정에 성공한 것입니다 !

API를 클릭하면

각 API에서 사용하는 파라미터, 설명 등의 정보와 테스트까지 가능합니다.

---

[참고 사이트]

egovframework:rte3.10:itl:swagger [eGovFrame]