Spring Rest Docs 도입 시, Maven과 Asciidoctor 문법이 헷갈리는 분들을 위한 pom.xml 설명

Spring Rest Docs를 검색했을 때, Maven에 도입하는 방법에 대한 pom.xml 설명이 부족하다고 느꼈습니다.

그래서 이번 글에서는 Spring Boot와 Maven(3.9.9 버전) 환경에서 Spring Rest Docs를 사용하기 위한 pom.xml 설정 방법을 정리하고, 그 과정에서 Maven 의 문법도 함께 학습해보려 합니다. 또한, pom.xml 설정 값들이 Asciidoctor와 Maven 중 누구의 설정 값인지 이해하는 것이 이 글의 목표입니다.

 

또한, 아래 그림과 같은 결과처럼 *.adoc 파일을 HTML로 변환하여 .jar 파일에 포함시키고, *.adoc 파일은 도메인별로 디렉토리를 나누어 관리하는 방식도 함께 구현해보겠습니다.

왼쪽) Maven의 .adoc 디렉토리 구조 / 중앙) Gradle의 .adoc 디렉토리 구조 / 오른쪽) Maven의 HTML결과물 위치

1. Spring Rest Docs 3.0.3 버전을 사용하기 위한 필요 조건

• Java 17
• Spring Framework 6

2. 의존성(dependency) 및 플러그인 추가

Spring Rest Docs를 사용하기 위해, Maven은 pom.xml, Gradle은 build.gradle 파일에 Build Configuration에 나온 빌드 설정을 추가해주어야 합니다.

 

Maven의 경우, {project-version}은 사용할 Rest Docs의 버전을 의미합니다. 이번 글에서는 Rest Docs의 버전으로 3.0.3을 사용할 예정이므로, {project-version} 자리에 3.0.3을 입력하면 됩니다.

 

3. Rest Docs로 만든 API 문서를 .Jar 에 패키징하기

프로젝트에서 Rest Docs를 이용해 API 문서를 만들었다면, 이제 이 문서를 다른 사람도 볼 수 있도록 배포해야 합니다. 이 과정을 Rest Docs에서는 "Packaging the Documentation"이라고 부릅니다.

 

Rest Docs는 빌드 시 API 문서를 /static/docs 경로에 포함하여 .jar 파일 안에 자동으로 문서를 넣어줍니다. 이 덕분에 우리는 HTML 파일을 따로 생성하거나 복사할 필요 없이, .jar 파일만 배포하면 편리하게 문서를 공유할 수 있습니다.

{IP주소:포트번호}/docs/index.html로 접근할 수 있습니다.

 

Rest Docs 공식 문서의 "Packaging the Documentation" 섹션에서 나오는 Maven 설정 중 3번 항목인 <outputDirectory>는 변환된 문서를 저장할 위치를 지정하는 태그입니다.

 

이 <outputDirectory>는 Asciidoctor 플러그인과 Maven 리소스 플러그인 둘 다에서 사용되는 태그 이름이기 때문에, "누구의 설정인지"는 해당 태그가 어떤 <plugin> 블록 안에 있는지를 보고 판단해야 합니다.

 

예를 들어 <plugin>이 maven-resources-plugin이라면, 이 <outputDirectory>는 Maven의 태그이며, asciidoctor-maven-plugin이라면 Asciidoctor의 태그입니다. 여기서는 <plugin>이 maven-resources-plugin 이기 때문에 Maven 태그입니다.

<plugin>
  <artifactId>maven-resources-plugin</artifactId>
  ...
  <configuration>
    <outputDirectory>${project.build.outputDirectory}/static/docs</outputDirectory>
  </configuration>
</plugin>

그리고 maven-resources-plugin은 src/main/resources/**와 같은 정적 리소스 파일들을 .jar에 포함시키는 역할을 합니다.

 

이 설정에서 사용된 ${project.build.outputDirectory}는 Maven의 속성으로, 컴파일된 클래스 파일들이 저장되는 디렉토리 경로를 의미합니다. 해당 속성의 기본값은 target/classes 입니다.

Maven pom.xml 속성 값 중 build.outputDirectory 설명

* Maven에서 빌드된 결과물의 주소 기본값은 target이며, Gradle의 빌드된 결과물의 주소 기본값이 build 입니다.

 

Maven 프로젝트를 빌드하면, src/main/java에 있는 .java 파일들은 .class 파일로 컴파일되어 target/classes 하위에 저장됩니다. 이 컴파일된 결과물들을 기반으로 .jar 파일이 만들어지고, 우리는 이 .jar를 실행하게 됩니다. 그렇기 때문에 API문서 역시 target/classes 하위에 위치시킵니다.

 

결론적으로 이 설정의 의미는 다음과 같습니다.

<outputDirectory>
	${project.build.outputDirectory}/static/docs
</outputDirectory>

HTML로 변환된 API 문서를 target/classes/static/docs 경로에 저장하고, .jar 파일 내에 해당 경로로 포함시켜, /docs/index.html 경로로 문서에 접근할 수 있도록 한다.

 

추가로 asciidoctor-maven-plugin 설정에서 등장하는 <backend>, <doctype>, <goals> 같은 태그들의 의미가 궁금하다면,  Asciidoctor 공식 문서 링크를 참고해보세요. Ctrl+F 를 통해 원하시는 태그의 설명을 찾으시면 됩니다. 

 

지금까지의 설정을 통해 아래와 같은 pom.xml 구성이 완성됩니다.
이 상태만으로도 .jar 파일에 API 문서가 포함되므로, Rest Docs를 배포 가능한 형태로 만들 수 있습니다.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>3.4.3</version>
		<relativePath/> <!-- lookup parent from repository -->
	</parent>
	...
	<properties>
		<java.version>17</java.version>
	</properties>
	<dependencies>
		<!-- API document -->
		<dependency>
			<groupId>org.springframework.restdocs</groupId>
			<artifactId>spring-restdocs-mockmvc</artifactId>
			<version>3.0.3</version>
			<scope>test</scope>
		</dependency>
	</dependencies>
	<build>
		<plugins>
			<plugin>
				<groupId>org.asciidoctor</groupId>
				<artifactId>asciidoctor-maven-plugin</artifactId>
				<version>2.2.1</version>
				<executions>
					<execution>
						<id>generate-docs</id>
						<phase>prepare-package</phase>
						<goals>
							<goal>process-asciidoc</goal>
						</goals>
						<configuration>
							<backend>html5</backend>
							<doctype>book</doctype>
						</configuration>
					</execution>
				</executions>
				<dependencies>
                	...
					<dependency>
						<groupId>org.springframework.restdocs</groupId>
						<artifactId>spring-restdocs-asciidoctor</artifactId>
						<version>3.0.3</version>
					</dependency>
				</dependencies>
			</plugin>
			<plugin>
				<artifactId>maven-resources-plugin</artifactId>
				<executions>
					<execution>
						<id>copy-resources</id>
						<phase>prepare-package</phase>
						<goals>
							<goal>copy-resources</goal>
						</goals>
						<configuration>
							<outputDirectory>
								${project.build.outputDirectory}/static/docs
							</outputDirectory> 
							<resources> 
								<resource>
									<directory>
										${project.build.directory}/generated-docs
									</directory>
								</resource>
							</resources>
						</configuration>
					</execution>
				</executions>
			</plugin>
		</plugins>
	</build>
</project>

 

4.  도메인별로 *.adoc 파일 나눠서 관리하기

더 나아가서 도메인 별로 *.adoc 파일들을 나눠서 관리하고자 합니다.

왼쪽) Maven의 .adoc 디렉토리 구조 / 중앙) Gradle의 .adoc 디렉토리 구조 / 오른쪽) HTML결과물 위치

 

Maven은 src/main/asciidoc 하위에 .adoc 파일을 두는 반면, Gradle은 src/docs/asciidoc처럼 main과는 나란한 경로를 사용합니다. 이런 차이는 아래 사진처럼 Spring Rest Docs 공식 문서에서 빌드 툴별로 .adoc 파일의 기본 구조를 명시해두었기 때문입니다.

Spring Rest Docs 3.0.3 의 *.adoc파일과 *.html 생성 파일 기본 값

 

아래는 도메인 별로 작성한 *.adoc 파일을 index.adoc에 include:: 문법으로 포함시키는 예시입니다.

= 게시판 API 문서
:doctype: book
:icons: font
:source-highlighter: highlightjs
:toc: left
:toclevels: 2
:sectlinks:

== 관리자 API
include::admin/admin.adoc[]

== 댓글 API
include::comment/comment.adoc[]

== 게시글 API
include::post/post.adoc[]

== 회원 API
include::user/user.adoc[]

 

도메인별로 나눈 디렉토리 구조를 그대로 결과물(target/generated-docs)에 반영하고 싶다면, <preserveDirectories> 태그를 true로 설정해줍니다.

Asciidoctor의 <preserveDirectories>태그에 대한 설명

<configuration>
    <backend>html5</backend>
    <doctype>book</doctype>
    <!-- 추가! -->
    <preserveDirectories>true</preserveDirectories> <!-- 해당 태그를 생략하면 기본값 false 적용 -->
</configuration>

다만, 저는 도메인별로 각각 HTML 파일을 생성할 필요가 없다고 판단했습니다. 결국 사용자 입장에서는 하나의 문서만 보면 되기 때문에, index.adoc만 index.html로 변환되면 충분하다고 판단했습니다.

그래서 <sourceDocumentName> 태그를 활용해 변환할 대상을 index.adoc 하나로 명시했습니다.

Asciidoctor에서 sourceDocumentName은 기본적으로 sourceDirectory 내의 모든 .adoc 파일을 처리하지만,
이 값을 설정하면 해당 파일 하나만 처리 대상으로 제한할 수 있습니다. 

<sourceDocumentName> : 기본값은 ${sourceDirectory}의 모든 파일입니다. ${sourceDirectory}는 asciidoctor 의 <sourceDirectory>태그를 의미합니다

<sourceDirectory> : 소스 파일이 위치한 경로입니다. 기본적으로 다음 경로들을 순서대로 확인합니다.
${basedir}/src/docs/asciidoc, ${basedir}/src/asciidoc, ${basedir}/src/main/asciidoc

 

Spring Rest Docs도 이 기본 경로를 그대로 사용하므로, *.adoc 파일들을 위 디렉토리에 위치시킨다면 <sourceDirectory>를 따로 설정할 필요도 없습니다. 결과적으로 아래와 같은 설정만 추가하면, 제가 의도한 대로 index.adoc만 index.html로 변환됩니다.

<configuration>
    <backend>html5</backend>
    <doctype>book</doctype>
    <!-- 추가! -->
    <sourceDocumentName>index.adoc</sourceDocumentName>
</configuration>

 

더 다양한 Asciidoctor의 태그들이 궁금하시다면 Asciidoctor Docs를 참고해주세요.

 

이 후, 재 빌드하여 빌드가 완료되면 target/generated-docs 디렉토리에 index.html 파일이 생성되고, 그 외에 도메인 별로 구성된 빈 디렉토리들도 함께 생성됩니다.

index.adoc만 index.html로 변환하기

(저는 도메인 별 비어있는 디렉토리들을 제거하고 싶어 여러 Asciidoctor 태그들을 시도해봤지만, Gradle에서는 가능했던 반면 Maven에서는 뚜렷한 해결 방법을 찾지 못했습니다. 혹시 이 부분에 대해 해결 방법을 알고 계신 분이 있다면, 댓글로 공유해주시면 정말 감사하겠습니다.)

 

그리고, target/generated-docs/index.html 파일을 열었을 때 문서가 깨짐 없이 정상적으로 보인다면 성공입니다.

 

5. Windows 환경에서 경로 구분 문제로 발생하는 Unresolved directive 오류 해결하기

Asciidoctor는 리눅스 기반의 경로 구분 방식을 따르기 때문에, 파일 경로를 /로 구분합니다. 하지만 Windows 환경에서는 \로 경로를 구분하기 때문에, 아래와 같은 경로 인식 오류가 발생할 수 있습니다.

Unresolved directive in admin/admin.adoc - include::..\..\..\target\generated-snippets/admin

 

저 역시 이 문제로 인해 API 문서가 제대로 출력되지 않는 상황을 겪었습니다. 이 문제를 해결하기 위해, Asciidoctor의 snippets 경로를 명시적으로 지정하고 /를 사용하는 방식으로 설정을 추가했습니다.

<configuration>
    <backend>html5</backend>
    <doctype>book</doctype>
    <sourceDocumentName>index.adoc</sourceDocumentName>
    <!-- 추가! -->
    <attributes>
        <!-- snippet 생성 위치 -->
        <snippets>${project.basedir}/target/generated-snippets</snippets>   
    </attributes>
</configuration>

${project.basedir} 은 현재 프로젝트가 있는 디렉토리를 의미합니다. ${ ... } 같이 Maven 의 POM 속성 값은 Maven 3.9.9 에서 "project" 란 명칭으로 시작합니다. POM 속성에 대해 더 알아보고 싶으신 분들을 위해 참고 링크 걸어두겠습니다. Maven 3.9.9 - POM Reference

pom.xml의 project.basedir 속성에 대한 설명

 

6. 마치며

Spring Rest Docs를 도입하면서 pom.xml에 필요한 설정들을 구성하는 과정에서, Maven 공식 문서와 Asciidoctor 공식 문서를 직접 참고하며 차근차근 이해해 나갔습니다. 처음 Gradle로 Rest Docs를 사용할 때는 빌드 툴 문법에 대한 이해 없이

그저 예제를 따라가기에 바빴고, 설정이 왜 그런 구조로 되어 있는지 깊이 고민하지 못했었습니다.

하지만 Maven으로 다시 Rest Docs를 도입하면서, 빌드 툴이 달라졌다는 이유 하나만으로도 예상보다 많은 시행착오를 겪게 되었고, 그 과정에서 자연스럽게 빌드 툴의 구조와 문법을 공부하게 되었습니다.

 

이 경험을 통해 특히 다음과 같은 점을 배울 수 있었습니다:

• pom.xml이나 build.gradle에 들어가는 설정값들 중 어떤 값은 플러그인 공식 문서를 참고해야 하고, 어떤 값은 빌드 툴(Maven/Gradle)의 문서를 확인해야 하는지를 구분하는 방법
• ${project.build.outputDirectory} 의 Maven 속성 값을 공식문서에서 확인하는 방법
• jar파일의 결과물이 컴파일된 .class 파일과 리소스 파일들을 압축한 것이라는 것 

이제 앞으로 다른 플러그인을 사용할 때도 필요한 설정이 무엇인지, 또 어떤 공식 문서를 참고해야 하는지를 보다 빠르고 정확하게 파악할 수 있을 거라 기대합니다.

 

참고 링크로 Maven의 pom.xml 속성 문서와 Asciidoctor의 Maven 설정 문서를 함께 정리해두었습니다.

Asciidoctor Docs

3.9.9 Maven Docs

Asciidoctor Maven Plugin Github