Spring Rest docs를 활용한 API 명세를 openapi3를 활용하여 swagger로 변환하기

 

 

 

 

최근 사내 카페 pos기 프로젝트에서 프로젝트의 API 명세를 어떠한 방법으로 사용 할 지를 팀원들과 고민하였고,

 

Spring Rest Docs를 사용하되 해당 정보를 openapi3를 활용하여 swagger로 띄우는 방법을 사용하기로 했다.

 

swagger보다 초기 설정이 어렵지만, 테스트코드를 강제할 수 있고 자동으로 API명세를 작성해주는 편리함이 있어서 사용을 한다.

 

openapi란, Restful한 API 디자인 정의의 표준이다.

 

즉, Api 스펙을 json 혹은 yml 형식으로 표현한 것이라고 이해하면 된다.

 

참고로, swagger는 openapi의 실제 실행 툴이라고 생각하면 된다.

 

 

---

 

먼저, Spring Rest Docs 사용을 위한 설정을 진행한다.

 

// build.gradle


plugins {
	...
    id 'org.asciidoctor.jvm.convert' version '3.3.2'
    id 'com.epages.restdocs-api-spec' version '0.16.0'
}

ext {
	snippetsDir = file('build/generated-snippets')
}

configurations {
	...
	asciidoctorExt
}

dependencies {
	...
	//mockMvc를 restDocs를 위해 사용할 수 있도록 도와주는 라이브러리이다.
	testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
    	//테스트 코드를 기반으로 각 테스트의 정보가 담긴 json 파일을 만들어주는 라이브러리
	testImplementation 'com.epages:restdocs-api-spec-mockmvc:0.16.0'

  	...
}

test {
	outputs.dir snippetsDir
}
asciidoctor {
	inputs.dir snippetsDir
	configurations 'asciidoctorExt'
	dependsOn test
}
tasks.named('test') {
	useJUnitPlatform()
}

openapi3 {
	servers = [
			{
				url = '서버 url'
				description = 'Development server'
			},
			{
				url = '로컬 url'
				description = 'Local server'
			}
	]
	title = '명세서 타이틀'
	description = '명세서 설명'
	version = '0.1.0'
	format = 'yaml'
}

 

Asciidoctor란, adoc형식의 파일을 html이나 pdf파일로 변환해주는 역할을 한다. 

 

해당 설정을 완료 후, RestDocumentationResultHandler를 만들어주는 메서드를 활용하여 테스트코드를 작성한다.

 

 

public abstract class EasyRestDocumentation {

    public static RestDocumentationResultHandler document(String operationId, String description, String tag) {
        ResourceSnippetParameters parameter = ResourceSnippetParameters.builder()
                .tag(tag)
                .description(description)
                .build();

        return MockMvcRestDocumentation.document(operationId, ResourceDocumentation.resource(parameter));
    }
}
    


// 테스트 코드
@Test
void 샵_정보_조회() throws Exception {
	ResultActions resultActions = this.mvc.perform(RestDocumentationRequestBuilders
                .get("/v1/shops")
                .contentType(MediaType.APPLICATION_JSON));

    resultActions.andDo(MockMvcResultHandlers.print())
                .andExpect(status().isOk())
                .andDo(EasyRestDocumentation.document("getShops", "샵 정보 조회", tag));
}

 

MockMvcRestDocumentation의 document 메서드의 경우 mvc.perform의 http 요청, 응답과 operationId, snippet을 활용하여 실제 adoc 및 json을 만들어주는 역할을 한다. 

 

이 후, gradle에 명시된 task인 openapi3가 실행이 되면, 각 테스트 폴더별로 존재하는 json 파일들을 모아서, 최종적으로 openapi3 형식을 갖춘 openapi-spec.yml파일을 생성하게 된다.

 

이 yml파일을 이제 swagger에서 가져다가 사용만 하면 된다!

 

우리의 경우, 사내 클라우드 시스템을 활용하여서 쿠버네티스를 활용하여 서비스 파드로 띄워 사용하였다.