반응형
1. RestDoc이란
- 테스트 코드 기반으로 Restful API 문서를 돕는 도구입니다.
- Asciidoctor를 이용해서 HTML 등등 다양한 포맷으로 문서를 자동으로 출력할 수 있습니다.
- RestDocs의 가장 큰 장점은 테스트 코드 기반으로 문서를 작성한다는 점입니다.
- API Spec과 문서화를 위한 테스트 코드가 일치하지 않으면 테스트 빌드를 실패하게 되어 테스트 코드로 검증된 문서를 보장할 수 있습니다.
장점
- 테스트 코드가 통과해야만 문서가 생성되므로 API 문서의 신뢰도가 높다
- API 문서 주석이 비즈니스 코드에 묻어나지 않는다.(swagger의 흔한 단점)
- 커스텀이 자유롭다
단점
- API 테스트 코드가 추가되면 문서 조각(Asciidoc snippet)을 합쳐주는 작업이 필요하다.
- Swagger 처럼 직접 API 테스트를 해볼 수 없고, 문서 가독성이 떨어진다. (디자인이 구림)
- 설정 복잡함
테스트 코드 예시
private MockMvc mockMvc;
@BeforeEach
void setUp(WebApplicationContext context, RestDocumentationContextProvider restDocumentation) {
this.mockMvc = MockMvcBuilders.webAppContextSetup(context)
.apply(MockMvcRestDocumentation.documentationConfiguration(restDocumentation))
.build();
}
@Test
void order() throws Exception {
mockMvc.perform(get("/api/v1/order")
.param("test", "testValue")
)
.andExpect(status().isOk())
.andDo(document("order Test",
preprocessRequest(prettyPrint()),
preprocessResponse(prettyPrint()),
resource(ResourceSnippetParameters.builder()
.tag("User API")
.summary("소셜 로그인 API")
.queryParameters(
parameterWithName("test").description("테스트 파라미터"))
.responseFields(
fieldWithPath("test").type(STRING).description("테스트 값"))
.requestSchema(Schema.schema("FormParameter-socialLogin"))
.responseSchema(Schema.schema("UserResponse.Login"))
.build())));
}
RestDoc 결과 화면
2. Swagger란
- Rest API를 편리하게 문서화 해주는 도구입니다.
- 제 3의 사용자는 문서에서 직접 API 호출 테스트를 진행할 수 있습니다.
장점
- 실시간으로 문서에서 API를 호출해보고, 응답 결과를 즉시 확인할 수 있음
- 어노테이션으로 간편하게 API문서를 만들 수 있음 (장점이자 단점)
- UI/UX 우수함
- 비교적 설정 간단
단점
- 비즈니스로직에 주석이 많아져서, 복잡해짐
- 코드와 문서 사이에 불일치가 발생할 수 있음 (어노테이션동작이기 때문에)
3. RestDoc + Swagger
RestDoc의 장점과, Swagger의 장점만 모두 사용해보자
동작 개념
- RestDoc을 이용했던 것 처럼 테스트 코드를 통해 docs 문서를 생성
- docs 문서를 OpenAPI3 스펙으로 변환 (springdoc-openapi 라이브러리를 통해)
- 만들어진 OpenAPI3 스펙을 SwaggerUI로 생성
- 생성된 SwaggerUI를 static 패키지에 복사 및 정적리소스로 배포
적용방법
gradle
buildscript {
ext {
restdocsApiSpecVersion = '0.18.2'
}
}
plugins {
id 'java'
id 'org.springframework.boot' version '3.4.4'
id 'io.spring.dependency-management' version '1.1.7'
// REST Docs 테스트 결과(문서조각)을 바탕으로 openapi(openapi3.yaml)을 자동 생성하는 플러그인
id 'com.epages.restdocs-api-spec' version "${restdocsApiSpecVersion}"
}
group = 'com.run'
version = '0.0.1-SNAPSHOT'
java {
toolchain {
languageVersion = JavaLanguageVersion.of(21)
}
}
repositories {
mavenCentral()
}
dependencies {
implementation 'org.springframework.boot:spring-boot-starter-security'
implementation 'org.springframework.boot:spring-boot-starter-web'
testImplementation 'org.springframework.boot:spring-boot-starter-test'
testImplementation 'org.springframework.security:spring-security-test'
testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
// rest docs 기본 라이브러리
testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
// rest docs와 openapi spec 플러그인을 연결해주는 Adapter
testImplementation "com.epages:restdocs-api-spec-mockmvc:${restdocsApiSpecVersion}"
}
// yaml파일 생성
openapi3 {
server = 'http://localhost:8080'
title = "RF API"
description = "RF API description"
version = "0.1.0"
format = "yaml"
}
// openapi.yaml 생성 + 정적 리소스 위치로 복사
tasks.register('copyOasToSwagger', Copy) {
from layout.buildDirectory.file("api-spec/openapi3.yaml")
into layout.projectDirectory.dir("src/main/resources/static/swagger-ui") // JAR 내 포함될 정적 리소스 경로
}
// 빌드 전에 swagger 파일 복사
tasks.named('build') {
dependsOn("openapi3", "copyOasToSwagger")
}
// 수동 실행용 문서 생성 task (test + openapi3 + copy까지)
tasks.register('generateSwaggerDoc') {
group = "documentation"
description = "Generate OpenAPI YAML and copy to static folder"
dependsOn("test", "openapi3", "copyOasToSwagger")
}
tasks.named('test') {
useJUnitPlatform()
}
결과 화면
http://localhost:8080/docs/index.html 에서 확인 가능
반응형
'프로그래밍 > SpringBoot' 카테고리의 다른 글
| [Spring boot] @Transactional의 예외처리 (checked, Unchecked Exception) (0) | 2022.11.16 |
|---|---|
| [spring security] csrf와 jwt의 관계 (0) | 2022.11.14 |
| [Spring boot 강의] #2 스프링부트 HTTPS / HTTP2적용하기 (0) | 2020.03.05 |
| [Spring boot 강의] #1 Spring Boot 프로젝트 실행하기 (0) | 2020.02.27 |
