Spring REST docs + asciidoctor + restdoc spec + swagger ui 를 통한 문서 자동화 - 개요

 

스프링에서 REST API 에 대한 문서화를 진행할 때 보통은 swagger + swagger ui 를 많이 사용하지만

• 개발코드에 문서화를 위한 annotation 을 지정해야함.
• API 가 업데이트 되었을 때 실수로 문서화에 대한 코드를 누락하여 실제 API 와 문서간의 동기화가 이루어지지 않을 소지가 있음.

과같은 단점이 있다.

 

위와 같은 단점을 해결하기 위해서는 스프링에서 제공하는 REST Docs + AsciiDoctor + Restdoc-spec + Swagger UI 를 통해서 개발코드를 오염시키지 않고 테스트 코드 기반으로 문서자동화를 구현할 수 있다.

 

물론 테스트 코드 기반으로 API 문서를 작성하기 때문에 보다 견고한 API 검증과 함께 문서화를 이룰 수 있는 장점이 있지만 적용하기 쉽지 않고 상당히 많은 양의 테스트 코드가 필요 할 수 있다는 단점 또한 존재하지만 문서화를 위해서 코드 수정을 피하고 싶은 경우 좋은 방안이라고 생각된다.

 

사전학습

mustache 와 asciidoc 문법에 대해서 알아두면 좋다.

• Asciidoc 레퍼런스
• Mustache 레퍼런스

 

OpenAPI vs Open API

• OpenAPI 는 API 문서화를 위한 specification 을 의미한다.
• Open API 는 말 그대로 공개된 API 를 의미한다.

각 모듈의 역할

Spring REST Docs	기본으로 제공되는 .snippet 파일 정의를 통해서 .adoc 파일을 생성
AsciiDoctor	Spring REST Docs 를 통해 생성된 .adoc 파일을 기반으로 html 문서를 생성 (maven plugin)
Restdoc-spec	Spring REST Docs 를 통해 생성된 .adoc 파일을 기반으로 OpenAPI-v3, OpenAPI-v2, postman-collection 형식의 파일을 생성
Swagger UI	Restdoc-spec 을 통해 생성된 OpenAPI 문서를 시각화

* HTML 형식의 문서화 제공이 필요없다면 AsciiDoctor 는 생략해도 무방하다.

---

관련 Dependency (Maven)

<properties>
    <asciidoctor.version>2.2.4</asciidoctor.version>
    <restdocs-api-spec.version>0.18.2</restdocs-api-spec.version>
    <restdocs-spec.version>0.22</restdocs-spec.version>
</properties>
...
<!-- spring REST docs 를 사용하기 위한 dependency -->
<dependency>
    <groupId>org.springframework.restdocs</groupId>
    <artifactId>spring-restdocs-mockmvc</artifactId>
    <scope>test</scope>
</dependency>
<!-- spring doc 를 통해 생성된 adoc 파일을 기반으로 openapi spec 문서로 변환하기 위한 dependency -->
<dependency>
    <groupId>com.epages</groupId>
    <artifactId>restdocs-api-spec</artifactId>
    <version>${restdocs-api-spec.version}</version>
    <scope>test</scope>
</dependency>
<!-- mockmvc 테스트에서 문서변환을 수행하기 위한 dependency -->
<dependency>
    <groupId>com.epages</groupId>
    <artifactId>restdocs-api-spec-mockmvc</artifactId>
    <version>${restdocs-api-spec.version}</version>
    <scope>test</scope>
</dependency>
<!-- OpenAPI spec 문서를 기반으로 swaggerUI 를 통한 시각화를 위한 dependency -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.1.0</version>
</dependency>

 

Maven 빌드 plugin

<build>
    <plugins>
        <!-- asciidoctor 을 실행하기 위한 plugin -->
        <!-- asciidoctor 은 spring doc 로 생성된 문서를 html 문서로의 변환을 수행한다 -->
        <!-- src/docs/asciidoc 내에 .adoc 가 정의되어 있어야 한다. -->
        <!-- openapi spec 으로 변환하기 위한 필수 옵션은 아니다. -->
        <plugin>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctor-maven-plugin</artifactId>
            <version>${asciidoctor.version}</version>
            <executions>
                <execution>
                    <id>generate-docs</id>
                    <phase>prepare-package</phase>
                    <goals>
                        <goal>process-asciidoc</goal>
                    </goals>
                    <configuration>
                        <backend>html</backend>
                        <doctype>book</doctype>
                        <attributes>
                            <project-version>${project.version}</project-version>
                            <snippets>${project.build.directory}/generated-snippets</snippets>
                        </attributes>
                        <!-- html 문서를 생성하기 위한 template 파일을 정의하는 설정이다 -->
                        <sourceDirectory>${basedir}/src/docs/asciidoc</sourceDirectory>
                        <sourceDocumentName>index.adoc</sourceDocumentName>
                        <!-- html 문서가 생성될 경로를 지정한다 -->
                        <outputDirectory>${project.build.directory}/classes/static/docs</outputDirectory>
                    </configuration>
                </execution>
            </executions>
            <dependencies>
                <dependency>
                    <groupId>org.springframework.restdocs</groupId>
                    <artifactId>spring-restdocs-asciidoctor</artifactId>
                    <version>${spring-restdocs.version}</version>
                </dependency>
            </dependencies>
        </plugin>
        <!-- spring doc 문서를 openapi spec 문서로 변환하는 plugin -->
        <plugin>
            <groupId>io.github.berkleytechnologyservices</groupId>
            <artifactId>restdocs-spec-maven-plugin</artifactId>
            <version>${restdocs-spec.version}</version>
            <executions>
                <execution>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                    <configuration>
                        <specifications>
                            <specification>
                                <!-- openapi-v2 spec 문서를 yaml 포맷으로 생성한다 -->
                                <type>OPENAPI_V2</type>
                            </specification>
                            <specification>
                                <!-- openvpi-v3 spec 문서를 json 포맷으로 생성한다 -->
                                <type>OPENAPI_V3</type>
                                <format>JSON</format>
                            </specification>
                            <specification>
                                <!-- postman collection 문서를 생성한다 -->
                                <type>POSTMAN_COLLECTION</type>
                                <filename>postman-collection</filename>
                            </specification>
                        </specifications>
                        <name>${project.artifactId}</name>
                        <version>${project.version}</version>
                        <!-- 테스트를 수행하기 위한 서버 host 정보를 설정한다 -->
                        <host>localhost:8080</host>
                        <schemes>
                            <scheme>http</scheme>
                        </schemes>
                        <!-- spring REST DOCS 를 통해서 생성될 .adoc 파일 경로를 설정한다 -->
                        <snippetsDirectory>
                            ${project.build.directory}/generated-snippets
                        </snippetsDirectory>
                        <!-- specification 항목에서 정의한 문서가 생성될 경로를 설정한다 -->
                        <outputDirectory>
                            ${project.build.directory}/classes/static/docs
                        </outputDirectory>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

위 maven plugin 항목에 대한 설명은 주석을 참고

 

HTML 문서 생성을 위한 asciidoctor template 정의

위 maven 빌드 plugin 정의에서 설정한대로 template 파일을 정의해야 한다.

<sourceDirectory>${basedir}/src/docs/asciidoc</sourceDirectory>
<sourceDocumentName>index.adoc</sourceDocumentName>

* 참고로 ${basedir} 혹은 ${project.basedir} 은 pom.xml 파일이 위치한 디렉토리 경로이다.

* maven 관련해서는 아래 링크를 참고

 

Maven – Introduction to the POM

<sourceDirectory /> <sourceDocumentName /> 에 정의된 대로 src/docs/asciidoc/index.adoc 에 asciidoc 파일을 생성하는데 미리 생성하는 것보다 spring REST Docs 를 통해서 .adoc 파일을 먼저 생성 후 그에 맞춰서 asciidoc 파일을 정의하는 것도 좋은 방법이라고 생각한다.

 

다음 장에서 문서화를 위한 샘플 코드를 작성해 본다.

Spring REST docs + asciidoctor + restdoc spec + swagger ui 를 통한 문서 자동화 (2)

---

 

Spring REST Docs 공식 문서 

Spring REST Docs