OpenAPI

프로그램끼리 주고받기로 약속한 창구를 열어 두면 그 약속을 어딘가에 적어야 합니다. 오랫동안 그 자리는 사람이 쓴 문서였습니다. 위키에 표를 하나 만들어 주소와 보내야 할 값과 돌아오는 값을 적어 두면, 연동하는 쪽은 그 표를 보고 코드를 짰습니다.

표와 코드는 한자리에서 관리되지 않으면 반드시 어긋납니다. 응답에 칸을 하나 더해도 위키를 고치는 일은 따로 기억해야 하고, 대개 기억나지 않습니다.

그래서 이런 대화가 매번 오갔습니다. "문서에는 사용자 이름이 온다고 돼 있는데 실제로는 안 오는데요." "아 그거 지난달에 뺐어요." 문서를 믿을 수 없게 되면 연동하는 쪽은 요청을 한 번 보내 보고 돌아온 결과를 눈으로 읽어 코드를 짭니다. 적어 둔 약속이 있는데도 매번 실물을 확인하는 셈입니다.

OpenAPI 는 그 약속을 사람이 아니라 기계가 읽는 형식으로 적자는 제안입니다. 형식이 정해져 있으면 파일 하나에서 사람이 읽는 설명서 화면도 나오고, 연동하는 쪽이 쓸 코드도 나오고, 실제 응답이 적힌 대로인지 검사하는 도구도 돌아갑니다. 문서를 고치는 일이 코드를 고치는 일에 붙어 버립니다. 2.0 판까지는 Swagger 라는 이름이었고 3.0 부터 지금 이름으로 바뀌어서, 두 이름이 지금도 섞여 쓰입니다.

파일 하나에 들어가는 것은 여섯 덩어리입니다. YAML 이나 JSON 으로 적는데, 둘 다 사람이 그대로 읽을 수 있는 텍스트 형식이라 편집기에서 바로 열립니다.

1. 기본 정보 — 규격의 판 번호, 이름과 설명, 실제 주소입니다. 운영 주소와 시험용 주소를 나란히 적어 둡니다.
2. 경로 — 열려 있는 창구의 목록입니다. /documents 처럼 주소를 적고 그 아래에 HTTP 메서드 별로 항목을 답니다. 같은 주소라도 읽기와 만들기는 다른 항목입니다.
3. 요청 — 각 항목이 받는 값입니다. 주소에 박히는 값, 물음표 뒤에 붙는 값, 헤더로 오는 값, 본문으로 오는 값을 자리별로 나눠 적고 각각의 모양과 필수 여부를 표시합니다.
4. 응답 — 돌려주는 값입니다. 상태 코드 별로 따로 적습니다. 200 일 때의 본문 모양과 404 일 때의 본문 모양이 다르기 때문입니다.
5. 스키마 — 여러 곳에서 되풀이되는 데이터의 모양을 한 번만 정의해 두고 이름으로 불러 씁니다. 문서 한 건이 어떤 칸들로 이뤄지는지를 적어 두면 목록 응답과 상세 응답이 같은 정의를 가리킵니다.
6. 보안 — 누구인지 확인하는 방식입니다. 토큰을 어느 헤더에 실어야 하는지를 적고, 창구마다 어떤 방식이 걸려 있는지 지정합니다.

문서 한 건을 새로 만드는 창구라면 이렇게 모입니다. 경로는 /documents, 동사는 만들기, 요청 본문은 제목과 내용 두 칸이고 제목이 필수입니다. 응답은 201 일 때 방금 만들어진 문서의 번호, 400 일 때 어느 칸이 잘못됐는지입니다.

쓰는 사람은 창구를 여는 쪽의 개발자이고, 읽는 쪽의 맨 앞에는 사람이 아니라 도구가 있습니다. 쓰는 방식은 둘로 갈립니다. 파일을 먼저 쓰고 그대로 구현하는 방식과, 코드에 표시를 달아 두고 거기서 파일을 뽑아내는 방식입니다. 앞쪽은 연동하는 쪽이 구현을 기다리지 않아도 되고, 뒤쪽은 코드와 파일이 떨어질 일이 적습니다.

도구가 이 파일로 하는 일은 넷입니다.

1. 설명서 화면 — 창구 목록과 각 창구의 입출력을 브라우저에서 읽게 그려 줍니다. 화면에서 값을 채워 요청을 직접 보내 볼 수도 있습니다.
2. 연동용 코드 — 파일에 적힌 창구마다 함수를 만들어 줍니다. 연동하는 쪽이 주소 문자열을 손으로 적지 않아도 됩니다.
3. 목 서버 — 구현이 아직 없어도 파일에 적힌 모양대로 가짜 응답을 돌려주는 서버를 띄웁니다. 화면 작업이 서버 작업을 기다리지 않고 나갑니다.
4. 검사 — 실제 요청과 응답이 파일에 적힌 모양과 같은지 자동으로 확인합니다. 문서와 동작이 어긋나는 일이 여기서 걸립니다.

사람 독자는 그다음입니다. 화면을 붙이는 개발자가 무엇을 보내야 하는지 확인하고, 밖에서 연동하는 개발자가 우리 제품에 붙을 수 있는지 판단하고, 프로덕트 매니저가 명세 문서에 적어 둔 화면 동작이 실제 창구로 가능한지 대조합니다. 명세 문서는 화면과 동작을 구현할 수 있을 만큼 구체화한 문서인데, 거기 적힌 목록 화면에 작성자 이름이 필요하다면 그 값이 응답에 있는지를 이 파일에서 봅니다.

"스펙 먼저 올려 주시면 목 서버 띄워서 화면부터 붙이고 있을게요."

구현을 기다리지 않고 파일만 받아 일을 시작하겠다는 제안입니다.

"응답에 오는 필드가 스펙에 없는데요. 어느 쪽이 맞는 거예요?"

파일과 실제 동작이 어긋났으니 둘 중 무엇을 고칠지 정하자는 말입니다.

"이번 변경 스펙에 반영했습니다. 필수 입력이 하나 늘어서 연동하신 쪽에 미리 알려야 합니다."

파일의 변경 내역이 곧 연동한 쪽에 생길 영향이라는 뜻입니다.

페이지덱은 다른 도구에서 문서를 끌어다 쓸 수 있게 창구를 열어 두고 있습니다. 태오는 그 스펙 파일을 코드와 같은 곳에 두고, 배포할 때마다 실제 응답이 파일과 같은지 검사하는 단계를 붙여 놓았습니다. 어긋나면 배포가 멈춥니다.

지현은 새 기능을 설계할 때 이 파일부터 엽니다. 화면에 필요한 값이 지금 창구로 나오는지 보고, 없으면 그 자리에서 태오와 무엇을 더할지 정합니다.

이 파일을 사람이 읽는 설명서로 여기는 경우가 가장 많습니다. 설명서 화면이 워낙 눈에 익어서 그 화면 자체를 OpenAPI 라고 부르게 되는데, 화면은 파일에서 나온 결과물이고 파일은 기계가 읽으라고 만든 규격입니다. 둘을 같은 것으로 보면 화면을 다듬는 데 시간을 쓰면서 파일이 코드와 맞는지는 아무도 보지 않게 됩니다.

파일만 있으면 문서와 코드가 저절로 맞는다는 기대도 자주 어긋납니다. 파일 하나에서 여러 산출물이 나온다는 설명을 듣고 나면 어긋날 자리가 없다고 느끼기 쉽습니다. 그런데 어느 방식이든 사람이 손으로 갱신하는 단계가 한 군데라도 남으면 거기서 다시 벌어집니다. 검사 단계를 배포에 붙여 두지 않으면 응답에서 칸이 사라진 브레이킹 체인지가 파일에는 그대로 남고, 그 파일을 믿고 연동한 쪽의 코드가 대신 멈춥니다.