## 내부 통신용 문서를 분리하는 가장 깔끔한 전략
네, 당연히 가능합니다! `index.adoc`은 일종의 **'메인 페이지'**일 뿐, Gradle의 Asciidoctor 플러그인은 `src/docs/asciidoc` 폴더 안에 있는 **모든 `.adoc` 파일을 각각 독립적인 HTML로 빌드**해줍니다.
내부 통신용 문서를 분리하는 가장 깔끔한 전략을 정리해 드릴게요.
---
### 1. 파일 구조 분리하기
먼저 폴더 구조를 아래와 같이 구성해 보세요.
Plaintext
```java
`src/docs/asciidoc/
├── index.adoc (외부 공개용 메인)
├── internal.adoc (내부 통신용 메인)
└── common/
├── error-codes.adoc (공통 에러 코드)
└── overview.adoc (개요)`
```
이렇게 파일을 두 개 만들면, 빌드 후 `build/docs/asciidoc/` 폴더에 `index.html`과 `internal.html`이 **각각 생성**됩니다.
---
### 2. 테스트 코드에서 타겟팅하기
테스트 코드에서는 스니펫이 저장될 **폴더 이름**만 잘 관리해주시면 됩니다.
- **외부용 테스트:** `.apply(document("public/user-get", ...))`
- **내부용 테스트:** `.apply(document("internal/system-config", ...))`
이렇게 경로를 나누면 `build/generated-snippets/` 아래에 `public`과 `internal` 폴더가 생겨서 관리하기 훨씬 편해집니다.
---
### 3. `internal.adoc` 작성 예시
내부 통신용 문서에는 외부 공개용과는 다른 '인증 방식'이나 '엔드포인트' 정보를 담으면 됩니다.
AsciiDoc
```java
= Internal Service API Reference
:doctype: book
:icons: font
:source-highlighter: highlightjs
:toc: left
== 시스템 간 통신 보안
내부 통신은 별도의 API Key를 사용하며, 내부망(VPN) 내에서만 접근 가능합니다.
== 내부 전용 API
include::{snippets}/internal/system-config/http-request.adoc[]
include::{snippets}/internal/system-config/response-fields.adoc[]`
```
---
### 4. Gradle 설정 팁 (특정 문서만 빌드하기)
만약 문서가 너무 많아져서 특정 파일만 빌드하고 싶다면 `build.gradle`에서 필터링도 가능합니다. (기본은 전체 빌드입니다.)
Gradle
```java
asciidoctor {
// 특정 파일만 HTML로 만들고 싶을 때
sources {
include 'index.adoc', 'internal.adoc'
}
}`
```
---
### 💡 시니어의 조언: 공통 조각 관리
내부용과 외부용 문서가 **공통으로 사용하는 에러 코드나 스니펫**이 있을 겁니다.
그럴 때는 `common-error.adoc` 같은 별도 파일을 만들고, `index.adoc`과 `internal.adoc` 양쪽에서 `include::common/error-codes.adoc[]` 방식으로 불러오면 **한 곳만 수정해도 양쪽 문서에 모두 반영**됩니다.
---
### 🛠️ Exception 문서화 기능 (추가 팁)
앞서 말씀하신 Exception 내용을 문서화할 때, **'내부 전용 에러'**와 **'외부 노출 에러'**가 다를 수 있죠?
- `internal.adoc`에는 시스템 스택 트레이스가 포함된 에러 응답을,
- `index.adoc`에는 사용자 친화적인 메시지만 담긴 에러 응답을 각각 인클루드하도록 구성하면 완벽합니다.
댓글
댓글 쓰기