Spring으로 REST API No.5(Spring REST Docs )

https://docs.spring.io/spring-restdocs/docs/2.0.2.RELEASE/reference/html5

Spring REST Docs

 

REST Docs -> 테스트를 하면서 문서 조각(snippets)를 만들 수 있으며, 이것들을 모아 문서화를 할 수 있다.

 

의존성은 프로젝트를 생성할 때 이미 추가했기 때문에 추가할 필요는 없고,

REST Docs를 적용하기 위해서는 @AutoConfigureRestDocs 어노테이션을 추가하면 된다.

 

.andDo(document("create-event"))

테스트에 create-event라는 문서를 생성하라고 하는 말 이다.

그럼 target 폴더에 create-event라는 문서조각(snippets)가 생성되어 있는데 읽기엔 꽤 불편하므로 

prettier를 적용시키고자 하면,

 

@TestConfiguration
public class RestDocsConfiguration {
	@Bean
	public RestDocsMockMvcConfigurationCustomizer restDocsMockMvcBuilderCustomizer() {
		return new RestDocsMockMvcConfigurationCustomizer() {
			@Override
			public void customize(MockMvcRestDocumentationConfigurer configurer) {
				configurer.operationPreprocessors()
					.withRequestDefaults(prettyPrint()) // Request 본문 이쁘게
					.withResponseDefaults(prettyPrint()); // Response 본문 이쁘게
			}
		};
	}
 }

RestDocs 환경설정 파일을 만들고,

 

 

@Import(RestDocsConfiguration.class)

해당 테스트클래스에 추가하면 된다.

 

정돈된 문서조각

[source,http,options="nowrap"]
----
POST /api/events HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/hal+json
Host: localhost:8080
Content-Length: 372

{
  "name" : "Spring",
  "description" : "REST API",
  "beginEnrollmentDateTime" : "2020-06-28T14:11:00",
  "closeEnrollmentDateTime" : "2020-06-29T14:11:00",
  "beginEventDateTime" : "2020-06-30T14:11:00",
  "endEventDateTime" : "2020-06-30T16:11:00",
  "location" : "부산역 어딘가",
  "basePrice" : 100,
  "maxPrice" : 200,
  "limitOfEnrollment" : 100
}
----

 

그리고 링크에 관한 문서조각이나 응답헤더 응답필드에 관해 설명을 덧붙이는걸 더 추가하고 싶을땐,

.andDo(document("create_event",
				links(
					linkWithRel("self").description("link to self"),
					linkWithRel("query-events").description("link to query-events"),
					linkWithRel("update-events").description("link to update-events")
				),
				requestHeaders(
					headerWithName(HttpHeaders.ACCEPT).description("accept header"),
					headerWithName(HttpHeaders.CONTENT_TYPE).description("content type header")
				),
				requestFields(
					fieldWithPath("name").description("Name of new event"),
					fieldWithPath("description").description("description of new event"),
					fieldWithPath("beginEnrollmentDateTime").description("beginEnrollmentDateTime of new event"),
					fieldWithPath("beginEventDateTime").description("beginEventDateTime of new event"),
					fieldWithPath("endEventDateTime").description("endEventDateTime of new event"),
					fieldWithPath("closeEnrollmentDateTime").description("closeEnrollmentDateTime of new event"),
					fieldWithPath("location").description("location of new event"),
					fieldWithPath("basePrice").description("basePrice of new event"),
					fieldWithPath("maxPrice").description("maxPrice of new event"),
					fieldWithPath("limitOfEnrollment").description("limitOfEnrollment of new event")
				)
		));

문서생성 코드에 document의 parameter로 snippets을 추가한다.

 

문서 빌드는 REST Docs의 래퍼런스에 있는 빌드 플러그인을 추가하고,

index.docs를 입맛에 맞게 바꾸고, src/main/asciidoc 안에 넣어준뒤, 테스트를 실행하면

아까 target 폴더안에 generate-docs 안에 index.html 문서가 있음을 확인 할 수 있다.