글을 작성하게 된 계기
외부 API 문서화에 대해 정리하기 위해 글을 작성하게 되었습니다.
1. 외부 API 문서화, 자동화의 필요성
외부 API 문서화는 단순한 문서 작업이 아니라, 팀 전체의 생산성을 높이는 방법 입니다. 외부 API 스펙을 자동으로 문서화하기 위해서는 외부 API를 문서화해야 하는 케이스 와 외부 API 문서화 방법 을 먼저 살펴보겠습니다.
- 외부 API 문서화 케이스
- 외부 API 문서화 방법
1-1. 외부 API 문서화 케이스
첫째는 공공 데이터 포털(Open API)처럼 누구나 접근할 수 있는 공개된 외부 API 입니다. 이런 경우에는 API 스펙이 제시 돼 있기 때문에 이를 그대로 참고하거나, 내부 문서에 포함 하는 것만으로 충분합니다.
이미 외부에서 제공하는 API 스펙이 있기 때문에 개발 편의를 위해 내부 문서에 포함하는 정도로 충분합니다.
두 번째는 비공개 API 입니다. 예를 들어 PG사와 VAN사, 은행, 카드사 간의 전문 통신 API 같은 경우인데, 이런 경우 반드시 계약 및 보안 규약에 따라 문서화를 해야 합니다. 스펙 자체가 대외비 로 분류되는 경우가 많기 때문이죠. 보통 PDF 형태 로 제공되거나, 사내 위키에 정리돼 있는데, 공유나 문서화가 아쉬운 경우 가 많습니다.
기업 간 계약에 따라 외부에 공개할 수도 있지만, 일반적으로는 내부 전용으로 관리하는 경우가 많습니다.
1-2. 외부 API 문서화 방법
첫 번째는 문서를 직접 작성 하는 방식입니다. 하지만 이 방식은 한계가 있는데, 언제 API 스펙이 변할지 알 수 없기 때문 입니다. 외부 서비스 제공자가 응답 필드를 추가하거나, 기존 필드의 자료형을 바꾸거나, 심지어 응답 구조 자체를 변경하는 경우가 발생할 수 있습니다. 이 경우 장애가 발생하게 되고, 오히려 혼란을 일으킬 수 있습니다.
최근 모 결제사에서 공지 없이 날짜 API 스펙을 변경해서 버그를 찾는다고 꽤 고생을 한 경험이 있습니다. 🥲
두 번째는 요청/테스트에 의한 자동화 방식입니다. 실제 API 호출 응답을 기반으로 문서를 생성 하거나, 테스트 시점에 응답을 캡처해 자동으로 스펙을 추출 해낼 수 있습니다. 이렇게 하면 스펙이 변경될 때마다 잘못된 응답이 오거나 테스트가 깨지니 금방 알 수 있고, 동시에 문서도 최신 상태로 반영할 수 있겠죠?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
@ActiveProfiles("test")
@AutoConfigureWireMock(port = 0)
@Execution(ExecutionMode.CONCURRENT)
@ExtendWith(RestDocumentationExtension::class)
@SpringBootTest(classes = [com.example.app.Application::class])
class AdviceApiDocumentationTest {
......
@Test
fun externalApiDocsTest(restDocumentation: RestDocumentationContextProvider) {
stubFor(
get(urlEqualTo("/advice"))
.willReturn(
aResponse()
.withHeader("Content-Type", "application/json")
.withBodyFile("advice-response.json")
)
)
given()
.filter(documentationConfiguration(restDocumentation))
.filter(
document(
"external-advice-api",
responseFields(
fieldWithPath("slip.id").description("조언의 고유 ID"),
fieldWithPath("slip.advice").description("조언의 내용")
)
)
)
.`when`()
.get("http://localhost:$wiremockPort/advice")
.then()
.statusCode(200)
}
}
2. 문서화 범위
우리가 실제로 문서화하려는 대상은 서비스가 호출하는 외부 API의 스펙 입니다. 따라서 전체 API 문서화를 시도하면 불필요하게 복잡해지고, 문서화의 본래 목적과도 어긋나게 됩니다. 즉, 서비스에서 외부 API를 호출하는 부분만 똑 떼어내어 문서화 해야 합니다. 아래 그림에서 3번 부분이 바로 문서화 대상이겠죠.
1
2
3
4
5
1.Controller
↓
2.Service → 3.외부 API 호출
↓
4.Repository
이렇게 하면 외부 API 스펙을 명확히 분리 할 수 있고, 내부/외부 API는 별도의 문서화 프로세스로 추적할 수 있습니다. 결과적으로 문서 관리가 단순해지고, 외부 API 변경 사항도 빠르게 감지할 수 있으며, 내부 서비스 로직 변경과는 독립적이고 안정적으로 유지할 수 있습니다.
1
2
3
4
5
6
7
8
9
10
# [ WebMvc 기반 테스트 ] - 1~4 전 프로세스를 포함한 API 스펙
1.Controller
↓
2.Service → 3.외부 API 호출
↓
4.Repository
# [ 외부 API 별도 문서화 ] - 3번 프로세스만 포함한 스펙
3.외부 API 호출 ---- 요청/응답 스펙 캡처 & 문서화
3. 고려할 점
추가로 고려할 점들도 있는데, 대표적으로 버전 관리 및 보안이 있을 것 같습니다. 오래된 서비스일수록 다양한 버전의 통신 스펙을 정의해두기 때문입니다. 또한 개인정보나 금융 정보가 포함될 수 있기 때문에, 마스킹 이나 암호화 같은 보안 조치도 반드시 필요하므로 이런 점도 고려해 보시길 바랍니다.
계약 관리: 계약과 스펙의 싱크를 맞추는 체계 필요스키마 검증: 자동화된 JSON Schema Validation 추가버전 관리: Git 기반으로 스펙 변경 이력 추적환경 차이 감지: 운영/테스트 응답 Diff 분석보안: 개인정보/금융정보 마스킹 필수공유 체계: 최신 문서가 자동 배포·공유되는 구조
4. 정리
외부 API 문서화는 단순한 문서 작업이 아니라, 팀 전체의 생산성을 높이는 방법 입니다. 특히 외부에 노출되지 않는 API라면 더욱이요. 구현 레벨은 각자 사용하는 언어나 프레임워크에 따라 다르기 때문에 별도로 다루지 않았는데, 조금만 검색해 보면 관련 자료가 많이 나오니 참고해 보시길 바랍니다.