Spring Rest Docs on

Swagger와 Spring Restdocs의 우아한 조합 (by OpenAPI Spec)

Tue, 22 Dec 2020 10:41:40 +0900

　MSA 환경에서의 API 문서화는 어떤 식으로 구성하는 걸까? 예컨대, 모듈이 10개 있다고 하면 각 모듈마다 API 문서가 만들어질 테고 API 문서를 클라이언트에 제공하기 위해서 각각의 (10개의) URL를 전달해야 할 텐데 이게 과연 효율적일까? 물론 기능별로 URL이 분리된다는 장점이 있고 굳이 모아보자면 각 API 문서를 다시 한번 크롤링 하여 검색할 수 있도록 제공하는 것도 하나의 방법이 될 수 있다. 하지만 이러한 방법들은 요구 사항을 위한 별도의 작업을 하게 되니 일을 위한 일이 되는 것 같아 뭔가 아쉬웠다. 좋은 방법이 없을까?

고민의 시작

　한창 궁금증이 머릿속에서 지워지지 않았을때 Spring 한국 스프링 사용자 모임 페이스북 그룹에 문의도 해가며 방법을 찾아가고 있었다.

닉네임이나 프로필 사진은 그들의 개인 정보를 위해 임의로 지정하였다.

　필자와 함께 개발자의 인생을 시작한 멋진 친구들에게 정확히 올해 6월 초에 고민을 털어놓으며 좋은 방법이 없을지에 대한 논의를 했던 적이 있다. 그런데 친구 중 한 명이 잊고 있었던 그 이슈에 대해서 다시 꺼내며 URL 하나를 던져준다. 참 고마운 친구들.

Shout out 34. asuraiv, black9p

언 반년이 지났으나 필자도 잊고 있었던 이슈를 그는 기억하고 있었다.

　올해 NHN FORWARD에서 진행했던 세션 중에서 MSA 환경에서 API 문서 관리하기: 생성부터 배포까지라는 제목의 내용이었고, 정확하게 필자가 고민했던 부분을 콕! 집어서 해결해 준 사례였다. 역시 세상엔 엄청난 고수들이 내가 고민했던 부분들을 이미(혹은 이후에라도) 고민하고 해결한 경우가 많다는 것을 느끼고 공유의 힘이 이렇게도 대단하구나 하며 놀라움을 금치 못하였다.

　이번 포스팅에서는 OpenAPI Spec 을 활용하여 Spring Restdocs로 만들어지는 문서를 Swagger UI에서 보는 흐름을 실제로 구현해 보고자 한다. 즉, Swagger 나 Spring Restdocs 뭐로 만들든 간에 OpenAPI Spec에 맞춰서만 만든다면 한곳에서 볼 수 있겠다는 희망이 보였다. 며칠 전 작성한 OpenAPI 와 Swagger-ui 포스팅을 본 독자들은 지금의 포스팅을 작성하기 위한 밑거름이었다는 사실을 눈치챘을 수도 있을 것 같다.

좋은 내용을 공유해 주신 (저의 고민을 완벽하게 해결해 주신) NHN FORWARD 발표자분께 이 포스팅을 빌어 감사의 인사를 보냅니다. :) 당장 팀 내에도 적용해봐야겠어요!!

Spring Restdocs에서 OpenAPI Spec 추출

　누가 또 친절하게 오픈소스로 만들어놨다. https://github.com/ePages-de/restdocs-api-spec 에서 관련 내용을 확인할 수가 있는데 해당 링크에서는 gradle 버전이고 https://github.com/BerkleyTechnologyServices/restdocs-spec 는 maven 버전이라고 한다. 마침 필자의 Github에 Maven 버전으로 SpringRestdocs를 세팅해둔 Repository 가 있어서 이를 활용해보고자 한다.

pom.xml 추가

　관련 dependency를 추가하자. jcenter라고 bintray.com 에서 운영되는 Maven Repository에 올려진 오픈소스이니 repository 도 추가해 주자.

<properties>
	<restdocs-api-spec.version>0.10.0</restdocs-api-spec.version>
	<restdocs-spec.version>0.19</restdocs-spec.version>
</properties>

<repositories>
	<repository>
		<id>jcenter</id>
		<url>https://jcenter.bintray.com</url>
	</repository>
</repositories>

<dependency>
	<groupId>com.epages</groupId>
	<artifactId>restdocs-api-spec</artifactId>
	<version>${restdocs-api-spec.version}</version>
	<scope>test</scope>
</dependency>

<dependency>
	<groupId>com.epages</groupId>
	<artifactId>restdocs-api-spec-mockmvc</artifactId>
	<version>${restdocs-api-spec.version}</version>
	<scope>test</scope>
</dependency>

위의 dependency에서 제공해 주는 모듈로 테스트의 SpringRestdocs를 만들었다면 OpenAPI Spec 을 만들어 주는 plugin 또한 추가해 주자

<pluginRepositories>
	<pluginRepository>
		<id>jcenter</id>
		<url>https://jcenter.bintray.com</url>
	</pluginRepository>
</pluginRepositories>

<plugin>
	<groupId>com.github.berkleytechnologyservices.restdocs-spec</groupId>
	<artifactId>restdocs-spec-maven-plugin</artifactId>
	<version>${restdocs-spec.version}</version>
	<executions>
		<execution>
			<goals>
				<goal>generate</goal>
			</goals>
			<configuration>
				<specification>OPENAPI_V3</specification>
				<format>JSON</format>
				<outputDirectory>${project.build.directory}/classes/static/docs</outputDirectory>
			</configuration>
		</execution>
	</executions>
</plugin>

위 plugin 설정을 보면 format 을 JSON으로 한 것을 볼 수 있는데 YAML로도 만들 수 있다. 자세한 사용방법은 위에서 명시한 링크를 참고해보는 게 좋을 것 같다.

SpringRestDocs를 SpringBoot에 적용하기

Sun, 08 Mar 2020 23:16:59 +0000

API를 개발하고 제공하기 위해서는 그에 해당하는 API 명세를 작성해서 사용하는 곳에 전달하게 된다. 어떤 URL에 어떤 파라미터를 사용해서 어떻게 요청을 하면 어떤 결과를 응답으로 내려주는지에 대한 관련 정보들. 이러한 “API 문서” 를 제공하는 방식은 상황에 따라 다양한 방법으로 사용되곤 한다.

API 코드와 해당 문서의 동기화가 자동으로 되어야 조금 편해질것 같다는 생각이 들었다.
출처 : https://dribbble.com/shots/3386291-API-Documentation

필자는 주로 “위키”(또는 일반 문서)를 활용해서 전달하곤 했었는데 API의 형태가 달라질 때마다 해당 위키를 수정해야만 하는 번거로움이 있었다. API 수정하면 위키도 수정하고. 깜박하고 위키 수정을 안하게 될 경우 왜 API 명세가 다르냐는 문의가… 그러다 알게된 Spring Rest Docs. (아무리 좋은 기술, 좋은 툴 이라 해도 실제로 본인이 필요로 하고 사용을 해야하는 이유가 생길때 비로소 빛을 발하는것 같은 느낌이다.)

이 포스팅에서는 swegger 와 비교하는 내용은 제외할까 한다. 워낙 유명한 두 양대 산맥(?)이라 검색해보면 각각의 장단점이 자세히 나와있기에…

최근 들어 TestCode 의 중요성을 절실하게 느끼고 있었고, TestCode 를 작성하면 자연스럽게 문서를 만들어 주는 부분이 가장 매력적이라고 생각이 들었다. 이를 반대로 생각하면, TestCode 가 실패할 경우 빌드 자체가 안되기에 어쩔수 없이 TestCode를 성공시켜야만 하고, 자연스럽게 정상적인(최신화 된) API 문서가 만들어지게 된다.

이번 포스팅에서는 다음과 같은 목표를 두고 실무에서 언제든지 활용이 가능한 약간의 “가이드” 같은 내용으로 작성해 보고자 한다.

Spring Boot 최신 버전에서 Spring Rest Docs 를 설정한다.
임의의 API 를 만들고 그에 따른 TestCase 를 작성한다.
Spring.profile 에 따라 Spring Rest Docs Url 을 접근 가능/불가능 할 수 있게 한다.

물론 필자의 방법이 다를수도 있지만, 이러한 방법을 토대로 보다 더 우아하고 아름다운 방법을 알아갈수 있지 않을까 하는 기대로.

Spring Boot 에 Spring Rest Docs 셋팅하고 TestCase 작성하기

우선 Spring Boot 프로젝트를 만든다. https://start.spring.io/ 에서 만들어도 되고 IDE 에서 제공하는 툴로 만들어도 되고. 만드는 방식은 무방하다. 그 다음 필요한 dependency 를 추가해 준다.

<dependency>
	<groupId>org.springframework.restdocs</groupId>
	<artifactId>spring-restdocs-mockmvc</artifactId>
	<scope>test</scope>
</dependency>

임의로 API를 작성하고

모델

@Getter
@Setter
public class Book {
	private Integer id;
	private String title;
	private String author;
}

컨트롤러

@RestController
public class BookController {

	@GetMapping("/book/{id}")
	public Book getABook(@PathVariable Integer id) {
		Book book = new Book();
		book.setId(id);
		book.setTitle("spring rest docs in spring boot");
		book.setAuthor("taetaetae");
		return book;
	}
}

해당 컨트롤러에 대한 TestCase 를 작성하자.

@WebMvcTest(BookController.class)
@AutoConfigureRestDocs // (1)
public class BookControllerTest {

	@Autowired
	private MockMvc mockMvc; // (2)

	@Test
	public void test_책을_조회하면_null이_아닌_객체를_리턴한다() throws Exception {
		mockMvc.perform(get("/book/{id}", 1)
			.accept(MediaType.APPLICATION_JSON))
			.andDo(MockMvcResultHandlers.print())
			.andExpect(MockMvcResultMatchers.status().isOk())
			.andDo(document("book", // (3)
				pathParameters(
					parameterWithName("id").description("book unique id") // (4)
				),
				responseFields(
					fieldWithPath("id").description("book unique id"),
					fieldWithPath("title").description("title"),
					fieldWithPath("author").description("author")
				)
			))
			.andExpect(jsonPath("$.id", is(notNullValue()))) // (5)
			.andExpect(jsonPath("$.title", is(notNullValue())))
			.andExpect(jsonPath("$.author", is(notNullValue())));
	}
}

(1) Spring Boot 에서는 해당 어노테이션으로 여러줄에 걸쳐 설정해야 할 Spring Rest Docs 관련 설정을 아주 간단하게 해결할 수 있게 된다. (참고)

(2) 공식 도큐먼트 에서는 4가지 방식을 말하고 있는데 이 포스팅 에서는 “MockMvc” 을 사용하고자 한다.

(3) “book” 이라는 identifier 를 지정하면 해당 TestCase 가 수행될때 snippets 가 생성되는데 해당 identifier 묶음으로 생성이 된다.