이전에는 API 문서를 노션에서 관리하였다. 여러 개발자가 다같이 설계하기에는 노션이 편리하기는 하나, 개발이 완료된 이후에는 사용하기에 불편한 점이 있다.

• 기본 협업 툴로 Jira 를 사용한다.
  • Jira 에서 다시 노션으로 접근하는 과정이 번거롭다.
• 변경에 유연하지 못하다.
  • 코드를 작성하다보면 사소하게 변경되는 사항들이 많이 생기는데 모든 변경점을 빠르게 적용하기 번거롭다.

따라서 별도의 API 문서 자동화 과정을 거치기로 하였다. 자동화 도구로는 RestDocs 와 Swagger 가 주로 언급이 되는데 프로덕션 코드와 완전히 독립적인 RestDocs 를 선택하였다.

적용 과정은 Spring Rest Docs 공식 문서를 참고하였다.

1. 의존성 추가 (build.gradle)

plugins { 
	id "org.asciidoctor.jvm.convert" version "3.3.2" // (1)
}

configurations {
	asciidoctorExt // (2)
}

dependencies {
	asciidoctorExt 'org.springframework.restdocs:spring-restdocs-asciidoctor:{project-version}' // (3)
	testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc:{project-version}' // (4)
}

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

test { 
	outputs.dir snippetsDir // (6)
}

asciidoctor { // (7)
	inputs.dir snippetsDir 
	configurations 'asciidoctorExt' 
	dependsOn test // (8)
}

• (1) : 내 프로젝트에 맞는 버전을 설정해준다.
• (2) : 의존성을 추가할 때 asciidoctorExt 설정을 사용하기 위해 추가한다.
• (3) : build/generated-snippets 폴더 내의 .adoc 파일에 자동적으로 매칭해주는 의존성을 추가한다.
• (4) : MockMvc 를 이용하여 테스트 코드를 작성하기 위해 추가한다.
• (5) : API 문서가 저장되는 위치를 설정한다.
• (6) : 테스트의 결과가 API 문서에 저장되도록 설정한다.
• (7) : asciidoctor 의 업무를 설정한다.
• (8) : 테스트가 수행된 후에 API 문서를 작성하도록 설정한다.

2. Jar 파일에 문서 추가

bootJar {
	dependsOn asciidoctor // (1)
	from ("${asciidoctor.outputDir}/html5") { // (2)
		into 'static/docs'
	}
}

• (1) : 빌드 전 문서를 미리 만들어놓도록 설정한다.
• (2) : static/docs 에 있는 문서들을 복사한다.

공식문서에서는 위의 예시만 포함되어 있다. 이는 .jar 이 실제로 만들어지는 배포 환경에서는 제대로 동작하나, 로컬에서 build 시에는 문서를 확인할 수 없다. 따라서 다음과 같이 별도의 copy 작업이 필요하다.