Portfolio

실행 환경 Spring Rest Docs Gradle 설정 적용 장점 단점 Swaager 알아보기 전에 알아야 할 개념 Swaager 종류 뭘 써야할까? 적용 장점 단점 우리들의 선택은? Reference

실행 환경

java : 11

gradle : 7.4.1

Spring Rest Docs

먼저 전 프로젝트에서 사용했던 Rest Docs를 보겠습니다.

Gradle 설정


plugins {
    id 'org.springframework.boot' version '2.7.1'
    id 'io.spring.dependency-management' version '1.0.11.RELEASE'
    id 'org.asciidoctor.jvm.convert' version '3.3.2'. // (1)
    id 'java'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '11'

configurations {
    asciidoctorExtensions   // (2)
}

repositories {
    mavenCentral()
}

ext {
    set('snippetsDir', file("build/generated-snippets")) // (3)
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    asciidoctorExtensions 'org.springframework.restdocs:spring-restdocs-asciidoctor' // (4)
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc' // (5)
}

tasks.named('test') {
    outputs.dir snippetsDir
    useJUnitPlatform()
}

tasks.named('asciidoctor') {  // (6)
    configurations 'asciidoctorExtensions'
    sources{
        include("**/index.adoc")
    }
    baseDirFollowsSourceFile()
    inputs.dir snippetsDir
    dependsOn test
}

asciidoctor.doFirst {     //(7)
    delete file('src/main/resources/static/docs')
}

task createDocument(type: Copy) {       // (8)
    dependsOn asciidoctor

    from file("build/docs/asciidoc")
    into file("src/main/resources/static")
}

bootJar {       // (9)
    dependsOn createDocument
}

(1) : gradle 7버전부터는 org.asciidoctor.jvm.convert 을 사용해야 합니다.

(2) : asciidoctorExtensions 을 설정해줍니다.

(4), (5) : asciidoctorExtensions 과 docs 생성을 위한 spring-restdocs-mockmvc 의존성을 추가해줍니다.

(6) : dependsOn으로 test task가 실행된 이후 실행되는 task입니다.

sources에 명시한 adoc만 html로 변환하게 해줍니다.
baseDirFollowsSourceFile의 경우 docs/asciidoctor/domain과 같이 폴더 구조로 adoc을 만들었을 때 index.adoc에서 include했을 경우 path를 찾지 못하기 때문에 설정해줘야 합니다.

(7) : 문서 최신화를 위해 앞전에 만들었던 docs파일을 삭제합니다. doFirst로 인해 asciidoctor가 실행되기 전에 실행하게 됩니다.

(8) : 완성된 html을 static 폴더에 넣어 서버를 띄우게 되면 볼 수 있도록 합니다.

(9) : bootJar가 실행되기 전에 createDocument task를 실행하게 됩니다.

이를 통해 build시에 docs파일이 jar파일에 들어갈 수 있습니다.

적용


@RestController
public class TestController {

	@GetMapping("/users")
	public ResponseEntity<TestResponse> get() {
		return ResponseEntity.ok(new TestResponse("test"));
	}


@SpringBootTest
@AutoConfigureMockMvc
@AutoConfigureRestDocs
class TestControllerTest {

	@Autowired
	private MockMvc mockMvc;

	@Autowired
	private ObjectMapper objectMapper;


	@DisplayName("레스트 독스 테스트")
	@Test
	void TestControllerTest() throws Exception {
	    // given

		// when
		mockMvc.perform(get("/users")
				.contentType(MediaType.APPLICATION_JSON_VALUE))
			.andExpectAll(
				status().isOk(),
				jsonPath("name").value("test")
			)

			// then
			.andDo(document("test",
				preprocessRequest(prettyPrint()),
				preprocessResponse(prettyPrint()),
				responseFields(
					fieldWithPath("name").type(JsonFieldType.STRING).description("테스트")
				)));
	}

}

테스트를 통해 스니펫을 생성해줍니다.

adoc 파일을 생성합니다 (src/docs/asciidoc)


ifndef::snippets[]
:snippets: ../../../build/generated-snippets
endif::[]
:doctype: book
:icons: font
:source-highlighter: highlightjs
:toc: left
:toclevels: 3
:sectlinks:
:docinfo: shared-head


== 예약 게스트 API

=== 예약 생성

==== Request

===== Request HTTP Example

include::{snippets}/test/http-request.adoc[]

==== Response

include::{snippets}/test/response-fields.adoc[]

===== Response HTTP Example

include::{snippets}/test/http-response.adoc[]