스프링에서 REST API 에 대한 문서화를 진행할 때 보통은 swagger + swagger ui 를 많이 사용하지만
- 개발코드에 문서화를 위한 annotation 을 지정해야함.
- API 가 업데이트 되었을 때 실수로 문서화에 대한 코드를 누락하여 실제 API 와 문서간의 동기화가 이루어지지 않을 소지가 있음.
과같은 단점이 있다.
위와 같은 단점을 해결하기 위해서는 스프링에서 제공하는 REST Docs + AsciiDoctor + Restdoc-spec + Swagger UI 를 통해서 개발코드를 오염시키지 않고 테스트 코드 기반으로 문서자동화를 구현할 수 있다.
물론 테스트 코드 기반으로 API 문서를 작성하기 때문에 보다 견고한 API 검증과 함께 문서화를 이룰 수 있는 장점이 있지만 적용하기 쉽지 않고 상당히 많은 양의 테스트 코드가 필요 할 수 있다는 단점 또한 존재하지만 문서화를 위해서 코드 수정을 피하고 싶은 경우 좋은 방안이라고 생각된다.
사전학습
mustache 와 asciidoc 문법에 대해서 알아두면 좋다.
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
A Project Object Model or POM is the fundamental unit of work in Maven. It is an XML file that contains information about the project and configuration details used by Maven to build the project. It contains default values for most projects. Examples for t
maven.apache.org
<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
Document RESTful services by combining hand-written documentation with auto-generated snippets produced with Spring MVC Test or WebTestClient.
docs.spring.io
댓글