😂 restdocs를 실무에 적용하며...

실무에서 restdocs를 적용하여 잘 사용하고 있었는데. 하나의 문제가 발생한다.

그 문제는 바로 api가 늘어날 수록 내 index.adoc의 길이도 늘어나고 api 수정을 해야할땐 해당 부분을 검색해서 찾기가 힘들다는 점이다... 거기에 더해 adoc 파일을 기준으로 생성된 html 파일도 api가 증가됨에 따라 스크롤이 계속 늘어난다는 점이다... 물론 옆에 목차가 있지만 목차에서도 찾아 간다해도 html 자체 크기가 너무 커지는 것이다 ㅜㅜ

📗 해결 방법

📄 adoc 작성

그래서 intellij에서 제공하는 방법과 링크를 통해 해당 문제를 해결해보았다.

[[문서 이름]]

adoc에 다음과 같이 작성해주면 주석? 느낌으로 작성이 되는데

intellij에서 다음과 같이 전구표시에 마우스를 클릭하면 추출 옵션이 나온다.

해당 방법으로 adoc 파일을 추출하면

파일 내에 adoc 파일들이 추출되어서 자동으로 생성된다.

여기서 주의할 점은

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

다음과 같은 설정이 있고 해당 설정을 사용하고 있다면 추출된 파일에도 동일한 설정을 추가해주어야한다.

📄 build html

그 후에 빌드 or ./gradlew asciidoctor 를 통해 html 파일을 생성하면

자신이 지정해놓은 폴더내에 index 외에 다른 html 파일들이 같이 생성된 것을 확인할 수 있다.

이제 해당 html에 접근할 수 있도록 설정해주어야하는데.

include::email-api.adoc[]

include::certification-api.adoc[]

위 파일을 추출했다면 다음과 같이 자동으로 치환되어서 나올텐데. 해당 설정으로 하면 html 파일의 길이가 계속해서 늘어나게 된다.

위에서 언급한 대로 나는 링크를 통해 api를 분리하고 싶기 때문에

=== 👉 link:email-api.html[Email 회원가입 및 로그인, window=blank]

=== 👉 link:certification-api.html[본인 인증, window=blank]

다음과 같이 link:{html 파일명}[노출될 문구, window=blank] 옵션을 통해 링크를 클릭했을 때 새창으로 뜰 수 있게 설정해주었다.

그럼 다음과 같이 링크가 된 상태로 확인할 수 있고 링크를 클릭시 새창으로 api 문서가 뜨는 것도 확인할 수 있다!