API 문서 개선과 문서화 툴 Stoplight로 변경하기

기존 프로젝트에서 API 문서를 Springdoc을 통해 OpenAPI 3.0 스펙에 맞게 자동 생성하여 Swagger UI 조합으로 사용하고 있었다.

아무래도 가장 익숙한 툴이기도 하고, 당시에는 Springdoc + Swagger UI 조합으로 가느냐, Spring Rest Docs를 사용하느냐에만 집중했기에 직접 서버에 테스트를 해볼 수 있다는 점에서 Swagger UI를 선택했었다.

하지만, 문서가 관리되지 않고 개발자들간 사용률이 점점 저조해지는 것을 발견했다. 그래서 이런 문제를 해소하고자 먼저 문서를 전반적으로 검토해보았다.

개선

1. 파라미터 설명 부재

요청과 응답 파라미터를 먼저 살펴보았는데, 설명이 붙어있는 것도 있지만 붙어있지 않고 단순히 example만 포함하여 운영되고 있는 것도 있었다. 그래서 이들을 통합하기 위해 모든 요청, 응답 파라미터에 부가 설명을 붙여주었다.

2. 어드민 기능의 노출
API 문서에 노출되지 않아도 되는 혹은 노출되지 않아야 하는 어드민 기능들의 API들이 고스란히 문서에 노출되고 있었다. 어드민 토큰이 있어야 동작하기에 그리 큰 문제는 아니지만 API 문서를 확인할 때 필요없는 것까지 노출될 필요는 없었기에 이를 `@Hidden` 어노테이션을 통해 감춰줬다.

기존에 컨트롤러들을 xxxWebApi라는 인터페이스로 문서화 해주고 있었는데, Admin 기능들은 대상에서 제외되어 있었다. 그래서 추가적으로 AdminWebApi도 생성해주었다.

이렇게 작게나마 개선을 진행했는데, 여기서 Swagger UI의 단점을 몇 가지 발견할 수 있었다.

단점

1. 스크롤 방식의 문서
Swagger UI는 스크롤 방식의 문서이다. 하나의 API에 집중할 수 있도록 구성되어 있기에 다른 API를 찾으려면 기존에 보고 있던 API의 토글을 접어야만 편하게 찾아볼 수 있다. 여기에 비슷한 API들이 여러 개 있다면 한번에 구분하기 어렵다는 단점도 있었다.

2. 응답 파라미터의 설명을 보기 어렵다 -> 가독성이 떨어진다
Swagger UI에서는 응답 파라미터의 설명을 보기 위해서는 응답에서 Schema를 선택하고, 여러 토글을 직접 눌러보면서 확인해야 한다. 그래서 타입이나 설명을 적어놔도 이런 것들이 존재하는지 조차 모르는 경우가 많았다.

그러다보니 자연스레 구두로 전달하는 일이 잦아졌다.

변경

위의 두 단점을 해소하면서 가독성이 좋은 문서화 툴 중 후보로 Scalar와 ReDoc, Stoplight Elements를 뽑았다. 하지만 ReDoc의 경우 내부에서 서버로 직접 테스트 하는 기능이 제공되지 않았고, 최종적으로는 Scalar, Stoplight Elements를 두고 경쟁했다.

1. Scalar
https://github.com/scalar/scalar

Scalar는 OpenAPI 3.0 명세에 따라 렌더링 하고 있으며 Notion과 비슷한 디자인을 가진 문서화 도구이다. 디자인 자체는 마음에 들었고, 가독성도 좋았지만 왜인지 위의 사진처럼 개요 부분을 선택했을 때 제대로 넘어가지 않는 버그가 있었다.

2. Stoplight Elements
https://github.com/stoplightio/elements

그래서 팀의 문서화 툴을 Stoplight Elements로 선택했다. 디자인도 수려했고, 가독성도 좋았다.

그리고 개요가 잘 선택되지 않는 문제도 없었다.

적용

적용은 간단했다. React Component를 이용한 방법처럼 다양하게 존재하지만, 정적 파일을 이용하는 방법을 사용했다.

<!doctype html>  
<html lang="ko">  
<head>  
    <meta charset="utf-8">  
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">  
    <title>코스픽 API 문서</title>  
    <meta name="description" content="코스픽 API 문서">  
  
    <!-- Stoplight Elements CSS -->  
    <link rel="stylesheet" href="https://unpkg.com/@stoplight/elements@8/styles.min.css">  
</head>  
<body>  
  
    <elements-api        apiDescriptionUrl="/v3/api-docs"  
        router="hash"  
        layout="sidebar"  
    />  
  
    <!-- Stoplight Elements JS -->  
    <script src="https://unpkg.com/@stoplight/elements@8/web-components.min.js"></script>  
  
</body>  
</html>

이외에도 application.yml에서 swagger-ui 관련한 설정을 제거하였다!

앞으로의 계획

아무래도 현재는 문서화에 들어가는 내용들을 직접 어노테이션으로 작성해줘야 하다보니 휴먼 에러가 들어갈 가능성이 존재한다. 그렇기에 이러한 문서 개선 작업을 진행했다. 하지만, 추후 API의 개수가 더 증가한다면, Spring Rest Docs와 RestDocs-Api-Spec를 함께 활용하여 OpenAPI 3.0 + Stoplight를 사용할 수 있도록 개선해볼 수 있을 것 같다.

저작자표시 (새창열림)

'개발 > 런세권' 카테고리의 다른 글

OSRM Match API로 러닝 코스 데이터 좌표 보정하기 (0)	2025.12.14
길찾기, 경로 보정의 핵심 OSRM 톺아보기 (0)	2025.12.08
프로젝트에서 Batch Job 로그에 MDC를 적용했다. (0)	2025.10.26
도메인 객체 생성 로직 관련 고민 (0)	2025.10.06
서버에서 지속적인 OutOfMemory가 발생하는 문제 해결 (3)	2025.09.29

🥊

API 문서 개선과 문서화 툴 Stoplight로 변경하기

개선

단점

변경

적용

앞으로의 계획

'개발 > 런세권' 카테고리의 다른 글

티스토리툴바

API 문서 개선과 문서화 툴 Stoplight로 변경하기

개선

단점

변경

적용

앞으로의 계획

'개발 > 런세권' 카테고리의 다른 글

'개발/런세권' Related Articles

티스토리툴바