문서화 툴 openapi3 + Stoplight 적용하기

배경

(아래 글에서는 openapi3 에 대해서는 다루지 않습니다. 관련 내용은 다른 블로그를 참고하시길 바랍니다.)

 

현재 API 문서는 openapi3 + Swagger-ui 조합의 자동화툴로 문서를 만들어왔습니다.

클라이언트 분들에게 가장 익숙한 툴이고 서버에 바로 API를 보내볼 수 있는 기능도 있어서 적절한 툴이라고 생각했었습니다.

하지만 Swagger-UI를 사용하면서 몇 가지 단점을 느끼게 되었고 이러한 단점을 개선한 다른 툴로 문서를 바꿔보려고 합니다.

 

 

어떤 단점이 있었는가?

개요의 부재

Swagger-UI는 리스트형식으로 API를 문서화하고 있습니다.

만약 유저에 관한 API를 보고 있는 중, 달리기에 관한 API를 보고 싶다면 기존에 보고 있던 유저 API를 접은 뒤,
달리기 API를 스크롤을 내리면서 직접 찾아야했습니다.

만약 API 개수가 적다면 큰 문제가 되지 않지만, 비즈니스 로직이 점점 복잡해지면서 API 개수도 늘어나고 있었습니다.

이러한 상황에서 개요의 부재는 개발 속도의 저하로 이어진다고 생각했습니다.

(다른 API 툴에서는 개요를 제공하는 경우가 많았습니다.)

 

가독성이 떨어진다.

가장 큰 단점이라고 느낀 부분은 Swagger-UI가 가독성이 많이 떨어진다는 것입니다.

비슷한 API 경로들이 많다면 내가 원하는 API가 뭔지 한 눈에 파악하기가 어려웠습니다.

 

API 설명 문서에서도 필드에 대한 설명이 바로 보이지 않았습니다.

특정 필드의 대한 설명을 확인하려면 Schma 선택 → 필드 선택 을 해야했습니다.

이 와중에도 Schma의 버튼도 작고 응답값이 여러 댑스 안에 있는 경우 지속해서 필드를 선택해야하는 번거로움이 있었습니다.

실제로 클라이언트 팀원분들 전부가 해당 필드의 대한 설명이 존재하는지도 모르고 계셨습니다..

따라서 더 보기 좋은 API 문서 툴로 바꾸는 것이 적절하겠다고 판단했습니다.

 

어떤 대안이 있는가?

우선 제가 API 툴을 선택하는 기준은 다음과 같았습니다.

 

1. openapi3를 활용한 툴

이미 Swagger-UI를 구축하면서 openapi3를 도입했었고 이를 활용한 툴들이 여러가지 있었습니다.

따라서 기존의 방식을 유지하고 빠르게 툴을 도입하기 위해서 openapi3를 활용하는 문서 툴 중에서 고르고자 했습니다.

 

2. 개요가 있어야 한다.

Swagger-UI를 사용하면서 개요가 없어 많이 불편했기에 개요가 들어있는 툴 중 선택하고자 했습니다.

 

3.무엇보다 가시성이 좋아야한다.

결국 가장 중요한 것은 한 눈에 원하는 정보가 들어오는가라고 생각합니다.

복잡한 문서속에서 원하는 정보들을 빠르게 파악해야 API 문서 툴로써 의미가 있다고 생각합니다.

위와 같은 기준을 만족하는 툴을 찾아보았고 저는 크게 2가지를 고려하게 되었습니다.

 

 

후보1. ReDoc

https://github.com/Redocly/redoc

ReDoc은 OpenAPI 명세 파일을 받아 가독성 높은 정적 HTML 문서로 렌더링해주는 오픈소스 도구입니다.

개요와 필드에 대한 설명이 한눈에 들어고 오른쪽에 예시도 보여서 가시성이 매우 좋다고 느껴졌습니다.

오픈 소스이기에 모든 기능이 무료로 제공되고 있었습니다.

하지만 저의 openapi3 파일을 통해 확인해본 결과, json 응답이 제대로 파싱되지 않고 단순 문자열로 나오고 있었습니다.

 

후보 2. Stoplight

https://stoplight.io/open-source/elements

Stoplight는 API 디자인, 문서화, 목(Mock) 서버, 테스트, 거버넌스를 모두 지원하는 통합 API 개발 플랫폼입니다.

ReDoc과 마찬가지로 가시성이 매우 좋은 툴입니다.

Stoplight는 ReDoc과 다르게 저희 서버 환경에 적용했었을 때 json이 제대로 파싱되고 있었습니다.

따라서 Stoplight를 채택하였고 이를 도입했습니다.

 

 

Stoplight 적용하기

https://github.com/stoplightio/elements

깃허브에 보면 어떻게 적용할 수 있는지에 대해 자세히 나와 있습니다.

 

정적 파일 다운로드 하기

여러가지 방법으로 적용할 수 있는데 저는 정적 파일로 적용하는 방식을 선택했습니다.

아래 링크에서 index.html 파일을 그대로 복사합니다.

https://github.com/stoplightio/elements/tree/main/examples/bootstrap

 

main 태그 내부에 apiDescriptionUrl 속성값을 제가 가지고 있는 openapi.yaml 파일 경로를 설정합니다.

<main role="main">
  <elements-api
    apiDescriptionUrl="openapi.yaml" // 나의 openapi.yaml 파일 경로
    router="hash"
  />
</main>

Nginx 설정하기

그리고 해당 index파일을 Nginx의 /usr/share/nginx/html/docs/stoplight/index.html 경로에 두었습니다.

(/docs/stoplight는 폴더를 만들어주었습니다.)

 

이때 위에 설정한 대로 openapi.yaml 파일을 찾을 수 있게 같은 경로에 openapi.yaml 파일을 위치시켰습니다.

../docs/
    └── stoplight/
        ├── index.html
        └── openapi.yaml

그리고 docs 경로로 오는 요청은 해당 페이지가 보이도록 설정합니다.

server {
    
    ...
    
    location /docs/ {
        alias /usr/share/nginx/html/docs/stoplight/;
        index index.html;
        try_files $uri $uri/ =404;
    }

    location = /docs {
        return 301 /docs/;
    }
}

작업을 완료했으면 Nginx를 재시작합니다. 저는 도커로 띄우고 있기에 도커로 재시작했습니다.

docker restart nginx

그러면 이제 /도메인/docs 접속시 문서 페이지가 보이는 것을 확인할 수 있습니다.

⚠️

operationId 값은 반드시 영문+문자 조합이여야 합니다.

위와 같이 영문과 문자 조합으로만 구성되어야 합니다.

만약 한글이나 화이트 스페이스가 포함되면 문서 페이지에서 사이드바가 제대로 동작하지 않습니다.

(몇 시간 삽질하고 알아냈습니다.. ㅠㅠ)