Spring REST Docs + Stoplight로 테스트 기반 API 문서 구성하기

이전 글에서 Swagger UI의 가독성 문제를 겪고 Stoplight Elements로 전환했었다. 당시 마무리에서 "추후 Spring REST Docs + RestDocs-Api-Spec 조합으로 구성할 예정" 이라고 남겼는데, 이번 프로젝트에서 실제로 해봤다.

기존 방식의 문제

어노테이션 기반 문서화는 코드와 문서가 분리되지 않는 것처럼 느껴지지만, 사실상 따로 논다.

프로덕션 코드에 @Operation, @Schema 같은 문서용 어노테이션이 가득 붙고, 실제로 API가 그 설명대로 동작하는지는 검증되지 않는다. 파라미터 타입이 바뀌어도, 응답 구조가 달라져도 문서는 모른다.

그래서 매번 API의 요청/응답 구조가 변경되면 어노테이션의 내용도 함께 변경해줘야 하는 컨텍스트를 기억해야 했다. 하지만, 이러한 컨텍스트의 증가는 개발자에게 좋지 않은 신호이기에 테스트가 통과해야만 문서가 생성되는 구조가 필요했다.

그래서 프로젝트 초기 팀원에게 이러한 의견을 전달하였고, 팀원도 공감하여 Spring REST docs + Restdocs-api-spec 조합으로 문서화 파이프라인을 구성했다. 하지만, 아직 안드로이드 개발자로부터 실질적인 가독성 문제에 대한 얘기가 없었으므로 swagger-ui를 통해 자동으로 생성되는 문서 페이지를 사용하도록 합의했다.

그리고 발생한 문제들

테스트에 적용한 내용이 반영되지 않아요!

기능을 개발하고 문서 테스트도 잘 작성하고 난 뒤, 만들어진 문서를 보면서 이상한 부분들이 목격되었다. 분명 문서 테스트에는 .summary(), .description()을 한글로 잘 작성했는데 문서에서는 이상하게 영어로 표시되거나 무시되는 것이다.

그리고 contentType이나 기타 여러 테스트 항목들이 제대로 먹히지 않는 이슈가 있었다.

 
그래서 왜 이러한 문제가 발생하는지 면밀히 원인을 조사해봤다.

문제의 원인은 springdoc은 기본적으로 런타임에 클래스를 스캔해서 자체 스펙을 /v3/api-docs로 자동 생성한다는 것이었다. 이로 인해 별도 설정을 하지 않은 현재 상황에서 기본 URL을 바라보니 테스트에서 작성된 내용이 아닌 런타임에 생성된 openapi3.yaml을 읽고 있던 것이다.

그래서 application.yml에 아래 내용을 추가하여 해결했다. [관련 PR]

springdoc:
    swagger-ui:
      url: /api-docs/openapi3.yaml

 
 

Swagger-ui의 가독성 문제

문서 테스트도 잘 작성하고, 설명도 충실히 했다고 생각하고 있었지만 지속적으로 안드로이드 개발자 분들에게 오는 메시지가 있었다. 그게 바로 아래와 같은 메시지이다.

 
이건 다른 프로젝트인 '런세권'에서도 겪었던 문제인데, 설명을 잘 작성해놓아도 swagger-ui 특성상 이를 확인하기가 쉽지 않다. 예를 들어 id에 대한 설명이 궁금하다면 아래 사진처럼 Schema를 선택하고 각 항목들의 토글을 눌러야 확인 가능하다. 
 

 
프로젝트 초기부터 지금까지 지속적으로 이러한 이야기가 나오는 것에 swagger-ui 보는 법을 가르쳐주는 것보다 추후 새로운 팀원 혹은 보는 방법을 까먹었을 경우를 대비해서 아예 새로운 툴인 'Stoplight'로 변경하기로 했다.

Stoplight를 선택한 이유는 이전 글에서 선택한 이유와 동일하며, 현재 익숙한 툴이었기 때문이다.

구성한 파이프라인

docsTest (RestDocs 태그 테스트)
  → openapi3 (스니펫 → OpenAPI YAML 생성)
    → copyOpenApiToStatic (YAML을 서빙 경로로 복사)
      → bootJar / bootRun

각 단계를 Gradle 태스크로 연결했다. docsTest는 @Tag("restdocs")가 붙은 테스트만 골라 실행하고, 스니펫을 build/generated-snippets에 쌓는다. openapi3 태스크(epages 플러그인)가 스니펫을 읽어 YAML로 만든다.

Stoplight Elements는 별도 서버가 필요 없다. HTML 파일 하나가 전부다.

<elements-api
    apiDescriptionUrl="/api-docs/openapi3.yaml"
    router="hash"
    layout="sidebar"
  />

springdoc 의존성도 제거했다. Stoplight HTML이 직접 YAML을 읽기 때문에 springdoc이 할 일이 없어졌다.

이러한 파이프 라인을 적용하면서도 여러가지 변경 사항을 추가로 적용했다.

JWT 보안 스키마 자동 패치 제거

swagger-ui에서는 보안 스키마를 붙여주지 않으면, 각 API 요약 옆에 자물쇠 아이콘이 붙지 않는다.

그래서 헤더에만 토큰이 필요함을 붙여놓으면 이를 한 눈에 파악하기가 쉽지 않았다. 하지만, Stoplight는 보안 스키마를 적용하지 않고, 헤더에만 노출해도 크게 불편한 점이 없다.

사진처럼 헤더가 명시되기 때문이다. 스키마를 적용한다고 해도 헤더 방식과 큰 차이점이 없다.
그래서 build.gradle에서 상당수를 차지하던 jwt 보안 스키마 자동 패치를 제거했다.

운영 서버 노출 문제

구성을 마치고 문득 "운영 서버에서도 문서가 보이는 거 아니야?" 라는 질문이 생각났다.

처음엔 static/docs/index.html을 Spring의 정적 리소스 경로에 뒀는데, 이 경로는 모든 환경의 JAR에 포함된다. 이전에 Springdoc을 쓸 때는 application-prod.yml에서 swagger-ui.enabled: false로 막았지만, 정적 파일은 그 설정으로 제어가 안 된다.

하지만 잠깐 생각해보니 굳이 복잡하게 막을 필요가 없었다.

운영 빌드 스크립트는 ./gradlew clean build -x test -x docsTest로 docsTest를 스킵한다. docsTest가 스킵되면 스니펫이 생성되지 않고, 스니펫이 없으면 YAML도 생성되지 않는다. YAML 없이 bootJar를 실행하면 JAR에 YAML이 포함되지 않는다. HTML 페이지가 열려도 YAML을 불러오지 못해 빈 에러 화면만 보인다.

의도적으로 막지 않아도 빌드 구조가 자연스럽게 운영 환경에서의 노출을 방지해주는 셈이다.

이에 반해 개발 서버 빌드는 ./gradlew clean build -x test로 docsTest가 실행되고, YAML이 생성되어 JAR에 포함되어 문서가 정상 서빙된다.

마치며

REST Docs 기반으로 바꾸고 나서 가장 좋은 점은 문서 신뢰도다. 테스트가 깨지면 YAML도 생성이 안되니, 문서와 실제 API가 다를 수 없다. 어노테이션을 없애는 대신 테스트 코드가 문서의 역할을 겸하게 되어 프로덕션 코드가 훨씬 깔끔해졌다.

Stoplight Elements는 여전히 만족스럽다. CDN 한 줄로 완성되는 UI치고는 퀄리티가 좋다. [관련 PR]