Asciidoc & Spring REST Docs로 API 문서 자동화

1. 왜 “코드로 쓰는 문서”인가?

• 싱크 걱정 끝 — 테스트가 실패하면 문서도 생성되지 않으므로 스펙 ≠ 코드 불일치가 사라집니다.
• CI/CD에 녹아드는 자동화 — 빌드만 돌면 최신 HTML이 배포되니 위키 수동 관리가 사라집니다.
• Swagger 대비 장점 — 운영 코드에 주석을 덕지덕지 붙이지 않아 가독성과 리팩터링 유연성이 유지됩니다.

2. 5분 만에 환경 준비하기

plugins {
    id 'org.asciidoctor.jvm.convert' version '4.0.2'   // Gradle 7+ 권장
    id 'org.springframework.boot' version '3.3.1'
}

dependencies {
    testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
    testImplementation 'org.junit.jupiter:junit-jupiter'
}

test {
    useJUnitPlatform()
    outputs.dir snippetsDir                             // 스니펫 출력 경로
}

asciidoctor {
    inputs.dir snippetsDir
    dependsOn test
}

tasks.register('copyDocs', Copy) {
    dependsOn asciidoctor
    from "${asciidoctor.outputDir}/html5"
    into 'src/main/resources/static/docs'               // 정적 리소스로 복사
}

Tip : bootJar { dependsOn copyDocs }를 추가하면 JAR 생성 시 자동으로 최신 문서를 포함합니다.

3. 테스트에서 스니펫 뽑아내기

@AutoConfigureRestDocs(outputDir = "build/generated-snippets")
@WebMvcTest
class MemberControllerDocTest {

    @Autowired MockMvc mvc;

    @Test
    void 가입_API() throws Exception {
        mvc.perform(post("/members")
                .contentType("application/json")
                .content("{\"name\":\"Yuna\"}"))
            .andExpect(status().isCreated())
            .andDo(document("member-create",
                    requestFields(
                        fieldWithPath("name").description("회원 이름")
                    ),
                    responseHeaders(
                        headerWithName("Location").description("생성된 리소스 URL")
                    )
            ));
    }
}

• MockMvc / WebTestClient / Rest-Assured 중 팀 스타일에 맞는 테스트 러너를 고르면 됩니다.

4. HTML 결과물을 서비스에 노출하기

1. src/main/resources/static/docs/index.html 아래에 자동 복사 → /docs/index.html 경로로 배포
2. Nginx 혹은 Spring WebMVC ViewController로 /docs에 리다이렉트 설정
3. PR마다 GitHub Pages · S3 · CloudFront 등으로 정적 호스팅해 “문서 프리뷰” 제공

5. 생산성을 높이는 실전 팁

• IDE 라이브 프리뷰: IntelliJ AsciiDoc 플러그인으로 .adoc를 실시간 렌더링합니다.
• 스니펫 재사용: 공통 헤더·에러 응답은 snippets/ 폴더에 모듈화해 중복 제거.
• Markdown 변환: 필요하면 org.asciidoctor.jvm.pdf · -doctypes=markdown 플러그인을 추가해 PDF·MD까지 뽑아낼 수 있습니다.
• Swagger ↔ REST Docs 병행: Spring REST Docs로 생성한 snippets를 springdoc-openapi-extension으로 합쳐 문서 일원화를 시도해 보세요.