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