Spring REST Docs vs Swagger: API 문서화를 완벽하게 관리하는 두 가지 방법

1. API 문서화의 필요성과 통합 관리의 장점

API 문서화는 개발자가 작성한 API에 대해 정확하고 이해하기 쉬운 정보를 제공하는 중요한 과정입니다. 이 과정은 여러 가지 이유로 필수적입니다:

• 개발자 간 의사소통: 팀 내에서나 외부 개발자와 협업할 때, API가 어떻게 동작하는지에 대한 명확한 설명이 필요합니다. 문서화된 API는 불필요한 커뮤니케이션 비용을 줄여줍니다.
• 유지 보수의 용이성: 프로젝트가 확장되거나 유지 보수 단계로 넘어갈 때, 문서화된 API는 빠른 파악과 문제 해결을 돕습니다.
• 사용자 및 클라이언트의 이해도 향상: 외부 클라이언트나 API를 사용하는 다른 팀들이 API를 쉽게 이해하고 올바르게 사용할 수 있도록 문서화는 필수적입니다.
• 테스트 및 품질 향상: API 문서는 테스트를 보다 정확하게 만들고, API 품질을 높이는 중요한 요소로 작용할 수 있습니다.

API 문서화를 통합 관리하면 다음과 같은 장점이 있습니다:

• 일관성 유지: 여러 서비스나 버전 간에 API의 일관성을 유지하고 관리할 수 있습니다.
• 자동화 도구와의 연동: Swagger나 Spring REST Docs와 같은 도구를 사용하면 코드에서 변경이 발생할 때마다 문서를 자동으로 업데이트할 수 있습니다.
• 중앙화된 참조: 모든 API 문서가 중앙화되어 유지보수 및 변경사항 관리가 용이해집니다.

반응형

---

2. Spring REST Docs의 특징과 Spring Boot 프로젝트에 적용하기

Spring REST Docs의 특징

Spring REST Docs는 테스트 기반으로 API 문서를 생성하는 도구입니다. 이는 실제 API 테스트 코드로부터 문서를 자동으로 생성하는 방식으로, 문서가 API와 항상 일치하는 것을 보장할 수 있습니다. 즉, 실제 API의 동작을 테스트하면서 문서가 생성되므로, 코드와 문서 사이의 불일치가 발생할 가능성이 적습니다.

주요 특징:

• 정확성: API 테스트 결과로 문서가 생성되므로 실제 동작과 일치하는 문서가 만들어집니다.
• 유연성: 다양한 형식(HTML, AsciiDoc 등)으로 문서를 생성할 수 있습니다.
• 코드 기반 문서화: API 변경 시 테스트와 함께 문서도 자동으로 업데이트됩니다.

Spring REST Docs 적용 예시 (Gradle 기반)

build.gradle

plugins {
    id 'org.springframework.boot' version '3.1.2'
    id 'io.spring.dependency-management' version '1.0.15.RELEASE'
    id 'java'
    id 'org.asciidoctor.convert' version '1.5.8'
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
}

test {
    useJUnitPlatform()
}

asciidoctor {
    dependsOn test
    inputs.dir snippetsDir
    outputs.dir file("build/asciidoc")
}

task copyDocs(type: Copy) {
    dependsOn asciidoctor
    from file("build/asciidoc/html5")
    into file("src/main/resources/static/docs")
}

테스트 코드 예시

import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultHandlers.print;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.preprocessRequest;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.preprocessResponse;

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.web.servlet.MockMvc;

@SpringBootTest
@AutoConfigureMockMvc
public class ApiDocumentationTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    public void documentApi() throws Exception {
        this.mockMvc.perform(get("/api/example"))
            .andExpect(status().isOk())
            .andDo(print())
            .andDo(document("example",
                preprocessRequest(),
                preprocessResponse()));
    }
}

위 코드를 실행하면, build/generated-snippets 디렉토리에 API 문서가 생성됩니다. 이 문서를 Asciidoctor를 통해 HTML, PDF 등으로 변환할 수 있습니다.

---

3. Swagger의 특징과 Spring Boot 프로젝트에 적용하기

Swagger의 특징

Swagger는 OpenAPI 명세를 기반으로 API를 문서화하고, 실제 API를 테스트할 수 있는 UI를 제공합니다. Spring Boot와의 통합은 springdoc-openapi 또는 swagger-spring-boot-starter 라이브러리를 통해 손쉽게 이루어집니다.

주요 특징:

• 자동화된 문서화: 코드에 정의된 애노테이션을 기반으로 자동으로 문서를 생성합니다.
• Swagger UI 제공: 웹 브라우저에서 API 명세를 확인하고, 테스트할 수 있는 인터페이스를 제공합니다.
• OpenAPI 표준 준수: OpenAPI 3.0 표준을 따르므로, 다른 도구 및 플랫폼과의 호환성이 뛰어납니다.

Swagger 적용 예시 (Gradle 기반)

build.gradle

plugins {
    id 'org.springframework.boot' version '3.1.2'
    id 'io.spring.dependency-management' version '1.0.15.RELEASE'
    id 'java'
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.1.0'
}

API 컨트롤러 코드 예시

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@Tag(name = "Example API", description = "API 문서화를 위한 예시 API")
public class ExampleController {

    @Operation(summary = "샘플 엔드포인트", description = "이 엔드포인트는 샘플 응답을 제공합니다.")
    @GetMapping("/api/example")
    public String exampleEndpoint() {
        return "Example response";
    }
}

이 코드를 작성 후, 애플리케이션을 실행하면 Swagger UI는 http://localhost:8080/swagger-ui/index.html에서 확인할 수 있습니다. Swagger UI를 통해 API 명세를 시각화하고, 각 API를 테스트할 수 있습니다.

---

4. Spring REST Docs와 Swagger 비교 및 각각의 장점

특징	Spring REST Docs	Swagger
문서화 방식	테스트 기반 문서화(정확성 보장)	애노테이션 기반 자동화 문서화(편리성 제공)
UI 제공 여부	별도의 UI는 제공하지 않음	Swagger UI로 API 테스트 및 시각화 가능
사용 사례	문서와 코드 일치가 중요한 프로젝트	자동 문서화 및 UI가 필요한 프로젝트
유연성	다양한 출력 형식 지원 (HTML, PDF, AsciiDoc 등..)	OpenAPI 표준에 기반한 문서화 지원
통합성	테스트 프레임워크와 통합하여 정확한 문서 생성	빠르고 직관적인 API 명세 및 테스트 환경 제

Spring REST Docs의 장점:

• 테스트 기반 문서화로 인해 API 동작과 문서의 정확한 일치 보장.
• 커스터마이징이 용이하고, 다양한 문서 출력 포맷을 지원.

Swagger의 장점:

• 애노테이션 기반으로 쉽게 적용 가능하며, Swagger UI를 통해 API 명세를 시각화하고 실시간 테스트 가능.
• OpenAPI 표준을 따르므로, 다른 시스템과의 호환성 및 통합성이 뛰어남

728x90

---

Spring REST Docs와 Swagger는 각각 다른 장점을 지닌 API 문서화 도구로, 프로젝트의 요구사항에 따라 적절한 도구를 선택하는 것이 중요합니다. REST Docs는 정확성과 테스트 연동이 중요한 경우에 적합하고, Swagger는 UI 기반으로 쉽게 API를 시각화하고 테스트할 수 있는 장점이 있습니다.