외부 서비스 문서를 보고 연동을 만들면서 필요한 기능이 없다고 판단했다. /ko/ 문서의 목차 십여 항목을 훑었는데 찾던 것이 없어서 다른 방법을 만들었고 우회하는 데 며칠이 걸렸다.
Table of contents
Open Table of contents
원인 — 판마다 다른 목차
나중에 /en/ 문서를 열어 보니 목차가 여섯 항목 더 많았고 그중에 내가 찾던 기능이 있었다.
번역이 안 된 것이었고 최신 기능일수록 영문에만 있었다. 한 판만 보고 없다고 판단한 것이 며칠을 만든 원인이었다.
조치 — 목차 대조와 규격 파일
그 뒤로는 두 판의 목차를 curl로 뽑아 comm -13으로 차집합을 냈다. 영문에만 있는 항목이 바로 드러난다.
$ curl -s https://docs.example.com/en/ | grep -oE '<a href="[^"]*">' | sort > en.txt
$ comm -13 ko.txt en.txt문서가 openapi.yaml 규격 파일로 제공되는 곳도 있어서 그쪽이 있으면 그것을 기준으로 삼았다. 경로와 메서드를 한 번에 뽑을 수 있고 문서보다 최신인 경우도 있어서 문서에 없는 POST /products/bulk 경로가 규격에는 있었다. 다만 규격에 있다고 실제로 되는 것은 아니어서 시험 환경에서 한 번씩 확인했다.
판단 기준 — 같은 항목의 다른 내용
목차가 같아도 내용이 갈리는 경우가 있었다. 한 항목의 상한이 한국어에서는 100건인데 영문에서는 500건이었고 변경 시점까지 적혀 있었다.
어느 쪽을 믿을지에는 두 가지 방법이 있었는데 상대에게 물어 답을 기다리는 것과 갱신 날짜로 가르는 것이다. 뒤쪽을 골랐다. 이유는 curl -sI로 두 판의 Last-Modified를 받아 비교하면 그 자리에서 판정이 나서다. /ko/가 몇 달 뒤처져 있었고 오래된 쪽을 믿지 않았다. 대신 갱신 날짜가 내용의 정확성까지 보장하지는 않는 것을 감수했고 그래서 실제 호출을 최종 판정으로 뒀다. 문서가 갈리면 최종 판정은 실제 호출로 했고 200건을 실제로 보내니 받아들여져서 영문 쪽이 맞았다.
확인한 것은 우리 docs/integrations/ 아래 문서에 적었다. 경로와 실측 결과와 함께 /ko/ 문서에는 이 기능이 없으니 /en/과 openapi.yaml을 보라는 것까지 남겨서 다음 사람이 같은 며칠을 쓰지 않게 했다.
문서에 없는 응답 필드
규격과 문서를 다 봐도 안 나오는 것도 있었다. 응답에 어디에도 설명이 없는 필드가 하나 섞여 왔다.
상대에게 물어보니 내부용이고 곧 없어질 것이라고 해서 쓰지 않기로 했다. 문서에 없는 것을 쓰면 상대가 없앨 때 조용히 깨지기 때문이다.
받은 응답에 모르는 필드가 있으면 Log::warning으로 남기는 코드를 넣어 뒀다. 새 필드가 생기는 것을 이것으로 알았는데 문서 갱신보다 응답이 먼저 바뀌는 경우가 실제로 있었다.
정리
- 한 언어판만 보고 기능이 없다고 판단하지 않는다
- 판마다 목차를 뽑아
comm으로 차집합을 대조한다 openapi.yaml이 있으면 그것이 가장 정확하고 문서보다 최신일 수 있다- 규격에 있다고 실제로 되는 것은 아니므로 시험 환경에서 확인한다
- 목차가 같아도 내용이 다를 수 있으니
Last-Modified를 본다 - 문서가 갈리면 실제로 호출해 본다
- 확인한 것과 어디를 봐야 하는지를 우리 문서에 적는다
- 문서에 없는 응답 필드는 쓰지 않고 로그로만 남긴다