[Spring Boot] Rest API Doc 문서 작성 (feat.asciidoctor)

 Spring boot를 쓰면서 API Document를 팀내에 전파할 방법을 고민중에 Asciidoctor를 이용한 방법이 있어 도입하게 됐습니다. 간단한 도입 방법과 사용법을 정리해보려 합니다.

 

 스웨거를 사용할 수 도 있지만 스웨거의 경우 어노테이션으로 코드 전체를 오염시켜야하는 치명적인 단점이 존재하여 선택하지 않았습니다. Rest API Doc은 MvcTest를 이용하여 작성하기 때문에 기존 코드를 오염시키지도 않고 테스트를 강제하여 정확한 결과를 표현할 수 있다는 장점도 있습니다.

 

 하지만 기본적인 문서작업과 정리해줄 문서 포맷을 작성해야하는 점이 있어 완벽한 자동화라고 말하기에는 부족하지 않나라는 생각도 들었습니다. (아직 사용이 미숙하여 그렇게 느낄 수도 있습니다!)

 

apply plugin: "org.asciidoctor.jvm.convert"


dependencies {
    asciidoctorExt 'org.springframework.restdocs:spring-restdocs-asciidoctor'
    testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
}

ext {
    snippetsDir = file('build/generated-snippets')
}

asciidoctor {
    sourceDir "src/docs/asciidoc"
    attributes = ['docsDir': "src/docs/asciidoc"]
    inputs.dir snippetsDir
    configurations 'asciidoctorExt'
    dependsOn test
}

asciidoctor.doFirst {
    delete file('src/main/resources/static/docs')
}

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

build {
    dependsOn copyDocument
}

test {
    useJUnitPlatform()
    outputs.dir snippetsDir
}

 위 셋업은 내가 필요로 한 정보를 담은 gradle세팅입니다.

 

저는 모듈 프로젝트를 사용하고 있어 plugin apply를 사용했지만 일반적으로는 

plugins {
    id "org.asciidoctor.jvm.convert" version "3.3.2"
}

해당 내용을 적용해주어야 합니다.

 

test를 수행했을 때  snippetsDir에 adoc파일들이 자동으로 생성됩니다.

asciidoctor 행을 보면 두 가지 sourceDir와 input.dir의 역할을 유의해서 입력해주어야합니다. sourceDir은 자동생성된 파일들을 다시 우리가 원하는 포멧으로 재생성해줄 소스 링크를 넣어줘야 합니다.

 input.dir는 snippetDir를 입력해주면 됩니다. 자동 생성된 input 파일들의 경로를 의미합니다.

 attributes는 소스에서 매핑되는 링크를 입력해주는데 사용합니다. adoc파일 내에서 숏링크로 docsDir를 설정해주는데 사용합니다.

 위 사진은 우리가 직접 생성해야하는 파일들입니다. consultation-detail.adoc은 자동으로 생성해준 snippets파일중 원하는 파일만 골라 모아준 파일이고 이런 각 api들을 한번 더 모아주는 파일이 index.adoc입니다.

 

<CONSULTATION-DETAIL.ADOC>

ifndef::snippets[]
:snippets: ./build/generated-snippets
endif::[]

== 진료 <Consultation>

=== 진료 조회

==== request parameter

include::{snippets}/consultation-detail/path-parameters.adoc[]

==== Request

include::{snippets}/consultation-detail/http-request.adoc[]

==== Response Fields

include::{snippets}/consultation-detail/response-fields.adoc[]

==== Example

include::{snippets}/consultation-detail/response-body.adoc[]

<INDEX.ADOC>

ifndef::docsDir[]
:docsDir: .
endif::[]

:toc-title: API Documentation
:toc: left
:toclevels: 2
include::{docsDir}/consultation-detail.adoc[]

https://narusas.github.io/2018/03/21/Asciidoc-basic.html  (asciidoc 파일 사용법입니다. 마크다운과 비슷하지만 다른 사용법입니다 ㅜㅜ)

 

추가적으로 api링크에 자동으로 위 파일들을 배포하기 위해 config 설정을 해주었습니다.

@Configuration
public class ApiApplication implements WebMvcConfigurer {

  public static void main(String[] args) {
    SpringApplication.run(ApiApplication.class, args);
  }

  @Override
  public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("/api-doc/**").addResourceLocations("classpath:/static/docs/");
  }
}

 저는 SpringApplication을 실행하는 메인 파일을 간략하게 Configurer로 활용했는데 상황에 따라 분리해주시면 됩니다. 위 설정을 마치고 build후 실행하면 {service-url}/api-doc/index.html 에 접속하여 api 문서를 확인할 수 있습니다.