Postman + OpenAPI + Redocly + Github Page = Fancy한 API문서

API문서는 개발팀끼리의 협업에 있어 반드시 필요합니다. API문서가 존재하지 않는다면, API를 사용해야 하는 당사자가 매번 직접 코드를 분석하여 필요한 스펙을 알아내야 할지도 모르겠습니다. 

 

저는 백엔드개발자로서 API문서를 여러번 작성해 봤습니다. Google Docs와 OpenAPI를 통해 작성을 해봤었는데 OpenAPI에 더 매력을 느끼게 되었습니다.

 

Google Docs는 무난하고 익숙했습니다. 어려서부터 '한글'을 주로 사용하면서 docs와 비슷한 환경에서의 문서작성을 해본 경험이 있었기 때문에 프로그램 내 도구들을 사용하는데 어려움이 없었습니다. 하지만 다목적 프로그램이니 만큼 형식이 없어 API문서의 필요한 요소들을 전부 만들어야 하는 부분이 큰 단점으로 여겨졌습니다. 실제로 제가 AtoZ를 모두 만들어 본 경험은 없고, 회사 내에서 이미 전해져 내려오는 형식을 이용했습니다. 이런 API문서는 특정 조직 내에서 공유되기엔 효율적일 수 있으나, 타 조직에 공유되기엔 불친절한 문서가 될 수 있겠다는 생각을 하게 되었습니다. 

 

OpenAPI(OpenAPI Specification, OAS)는 REST API에 대한 표준을 기준으로 작성하는 API정의서가 되겠습니다. 표준을 기준으로 작성하기 때문에 어느 누가 작성하던 동일한 형식의 문서가 나오게 됩니다. 이는 협업의 측면에서 매우 큰 장점이라고 볼 수 있습니다. OpenAPI는 json 또는 yaml의 포맷으로 작성하게 됩니다. 제가 느꼈던 큰 단점으로는, yaml파일의 형태로 작성하게 될 경우 디버깅이 매우 힘들다는 점이 있습니다. 들여 쓰기를 조금이라도 잘못하거나 규칙에 맞지 않을 경우 매우 추상적인 에러메시지를 주게 되는데 이는 자칫 긴 시간을 디버깅에 투자하게 만듭니다. 하지만 이러한 단점을 저는 chatGPT의 도움으로 해결했습니다. 스크립트를 복사하여 ChatGPT에 문제 되는 부분을 알려달라고 하면 친절하게 알려줍니다. OpenAPI의 표준은 공식사이트등을 통해서 알 수 있지만 chatGPT를 통해서도 쉽게 작성할 수 있는 시대가 되었습니다. OpenAPI를 사용하지 않을 이유가 없습니다. 

 

하고싶은 말이 많아 서론이 길어졌습니다.

 

제목에 나타나 있는 조합은 제가 경험한 간결하면서도 강력한 조합입니다. 이 도구들을 통해 API문서를 어떻게 만들 수 있었는지 제 경험을 기반으로 알려드리겠습니다. 아래 링크는 제가 만든 예시입니다.

https://mmmmicha.github.io/newsfeed.api/docs/index.html

newsfeed.api

 

1. Postman Collection을 Export 합니다.

Postman을 익숙하게 사용하신다는 전제하에 설명을 드리겠습니다.

아래 첨부된 사진들을 순서대로 실시하여 json파일을 준비해 주시면 됩니다.

 

Collection옵션에서 Export를 클릭합니다

 

Export버튼을 클릭합니다

 

json파일로 export를 성공했습니다

 

2. Postman to OpenAPI

export 한 Postman json파일을 OpenAPI Specification에 적합한 yaml파일로 변환합니다.

 

먼저 아래의 명령어를 통해 필요한 라이브러리를 설치합니다.

npm i postman-to-openapi -g

 

 

라이브러리를 설치했으면 적당한 디렉터리경로를 잡고 아래 명령어를 실행합니다.(저는 download폴더에 json파일을 두고 터미널 내 download에 위치한 상태에서 진행했습니다.)

collection파일의 이름을 알맞게 명시하시고 yml파일의 이름 역시 명시해 주세요.

p2o ./PostmantoCollection.json -f ./result.yml

 

이렇게 하시면 Postman to OpenAPI 과정 역시 완료입니다.

 

3. Redocly

Github Pages에 작성한 OpenAPI를 배포하기 위해서는 yml파일을 html로 변환하는 작업이 필요합니다. 이를 도와주는 라이브러리로 Redocly가 있습니다. 아래 과정대로 진행해 줍니다.

 

Redocly라이브러리를 설치합니다.

npm install @redocly/cli -g

 

 

앞서 OpenAPI표준형태로 바꾼 yml파일이 있는 경로에서 아래와 같은 명령어를 통해 yml-to-html변환을 진행합니다. 아래의 결과로 redoc-static.html파일을 얻을 수 있습니다.(만약 yml확장자 때문에 오류가 발생한다면 파일의 확장자를 yaml로 변경하고 진행합니다.)

redocly build-docs openapi.yaml

 

4. Github Pages 배포

Github Pages에 대한 배경지식이 없으신 분들은 아래 링크를 통해 QuickStart 해보시기 바라겠습니다.

https://docs.github.com/en/pages/quickstart

Quickstart for GitHub Pages - GitHub Docs

 

사전 과정들을 통해 OpenAPI Specification에 맞는 파일 준비는 완료되었습니다. 이를 Github Pages에 배포함으로써 많은 사람들이 접근할 수 있는 환경을 만들면 되겠습니다. 저는 API문서의 근간이 되는 리포지토리에 Github Page를 생성하여 해당 페이지에 배포를 진행했습니다. 

newsfeed.api 라는 리포지토리에 Pages를 만든 모습입니다

 

위와 같이 프로젝트의 리포지토리에 Page를 생성했습니다.

 

3번 과정에서 만들었던 redoc-static.html파일을 index.html파일로 이름 변경 후 origin/main으로 푸시합니다.(주목할 부분은 main브랜치를 push 하여 origin으로 동기화시켰을 때만 Pages에도 적용이 된다는 점입니다. 저는 위 사진처럼 main을 푸시해야만 Pages에 적용되도록 설정을 했기 때문입니다.)

저는 아래 사진과 같이 docs라는 폴더를 따로 만들어 배포를 진행했습니다. 그 결과로 https://mmmmicha.github.io/newsfeed.api/docs/index.html이라는 경로로 접근할 때 OpenAPI가 보이게 되었습니다.(URL을 보면서 경로에 대해 이해해 보세요. 추후 Github Pages를 이용하게 되면 확장된 사용이 가능할 것입니다.)

docs폴더 내 index.html이 있는 상황

 

newsfeed.api프로젝트를 기반으로 만든 OpenAPI를 배포한 모습

 

이렇게 간결하면서도 강력한 OpenAPI작성부터 배포까지의 방법을 공유드렸습니다. 이 방법은 말 그대로 가장 기초적인 방법이라 문서를 자세히 작성하기 위해서는 위에 공유드렸던 공식사이트를 방문하여 찾아보는 방법이나 chatGPT를 이용한 작성을 권장드리겠습니다. 누군가에게 이 경험공유가 큰 도움이 되었으면 좋겠습니다.

 

감사합니다.

 

참조: https://gruuuuu.github.io/programming/openapi/ 

https://joolfe.github.io/postman-to-openapi/

https://github.com/Redocly/redocly-cli