Spring Rest docs 와 Swagger 장점만 골라서 사용하기

소개

테스트 문서 자동화 도구를 검색하면 두 가지 옵션이 있는데 하나는 Spring REST docs이고 하나는 Swagger이다.

Swagger는 예쁜 UI를 제공하고 제공된 UI를 통해서 request를 날릴 수 있는 좋은 도구이지만 소스 코드에 API 문서 자동화와 관련된 코드를 추가해야 하는 단점이 있고

Spring REST docs는 소스 코드에 API 문서와 관련된 코드가 없이 정갈하게 만들 수 있으며 만들어진 문서는 모두 테스트를 통과해야 작성되는 제약을 가지고 있기 때문에 문서의 신뢰성을 높다는 점이 매력적이다.

그래서 개발자의 취향에 따라서 요구에 따라서 어떤 스택을 선택하는지가 달라지는 것 같은데 어쩌다보니 두 가지를 혼용하여 사용하는 방법이 있다는 것을 알게 되어서 바로 시도해 보았다.

swagger는 스프링의 전유물이 아니다?

처음 swagger를 알게 되었을 때는 spring에서 어노테이션으로 명세를 작성하는 것을 보고 java 진영에서 개발한 그런 것인 줄 알았다. 하지만 알고 보니 swagger는 자바뿐만이 아니라 다른 언어를 사용하더라도 사용할 수 있는 기술이었다. 자바에서 swagger를 사용하기 위해서 어노테이션을 제공하는 것이었을 뿐....

swagger ui는 이름처럼 ui를 제공하는 그 기능을 담당한다. swagger ui를 라이브러리를 사용해서 스프링 부트 서버를 운영할 때 같이 사용하거나 할 수도 있고 독립적으로 swagger 서버를 운영할 수도 있다.

연동을 어떻게 하는가?

swagger는 openapi 규격을 준수한다. 그래서 openapi에 맞는 데이터 포맷을 사용해서 swagger에게 알려주면 기대한 API 문서를 만들 수 있다.

그럼 이 openapi 에 맞춘 문서를 spring rest docs 기반으로 만들면 되는데... 아직 스프링에서 이런 기능을 공식적으로 제공하는 것 같지는 않다. 나중에 뭐 제공할 수도 있을 것 같다는 생각이 드는데 현시점에서는 없고 구글링 하다가 한 오픈 소스를 알게 되어서 그것을 활용하면 가능하다.

오픈 소스 프로젝트

이 프로젝트는 spring rest docs의 명세를 기반으로 만들어진 오픈 소스이다. 기존의 spring rest docs는 asciidoctor를 통해서 문서를 만들어주는 것이었지만 이 프로젝트는 openapi 를 만들어준다.

(이러한 파일이다. ./build/api-spec/openapi3.yaml)

테스트 코드 작성은 거의 동일하고 관련된 패키지만 다르게 설정하면 되었다. 더 자세한 설명은 다음 깃허브를 참고해서 상황에 맞게 사용하기를 바란다. 내가 사용한 설정은 다음과 같다.

 

GitHub - ePages-de/restdocs-api-spec: Adds API specification support to Spring REST Docs

plugins {
	...
    // spring rest docs with open api
    id 'com.epages.restdocs-api-spec' version '0.18.2'
}

dependencies {
	...
    // spring rest docs with open api
    testImplementation('com.epages:restdocs-api-spec-mockmvc:0.18.2')
}
...

// 가이드 보고 설정한 task
openapi3 {
    server = 'http://localhost:8080'
    title = 'MyApp'
    description = 'API document'
    version = '0.1.0'
    format = 'yaml'
}

swagger 서버를 만들자.

springdoc.org 이 프로젝트를 사용하면 스프링 부트가 swagger 서버를 같이 구동하게 해 준다.

처음에는 이것을 활용해서 구축하려고 시도했지만 소개해준 블로그를 참고해도 쉽지 않았다.

특히 만들어진 openapi3.yaml 문서를 어떤 디렉터리에서 관리할 것이며 빌드할 때마다 이 파일을 복사하는 작업을 해주거나 하는 설정을 build.gradle에 추가해야 했다.

이는 build.gradle을 지저분하게 만들어서 읽기가 힘들게 만든다는 느낌이 들었다.

 

그래서 도커 기반으로 서버를 구동하는 방법을 선택하기 방향을 잡았다.

서버를 분리하면 나중에 서비스를 분리하여 도메인 별로 서버가 가동되더라도 API 관련 URL만 추가설정하면 손쉽게 명세가 추가가 가능하고 build.gradle의 복잡성 역시 해소되어서 좋다고 판단했다.

또한 가동 시에 실행하는 과정이 추가되고 도커에 의존성이 생긴다는 문제가 있지만 도커 컴포즈를 활용하면 추가되는 과정 역시 쉽게 진행할 수 있고 도커 의존성 역시 도커를 한 번만 다운하고 이미지 역시 한번만 다운하면 되기 때문에 크게 문제가 될 사항은 아니라고 판단했다.

services:
  swagger-server:
    image: swaggerapi/swagger-ui
    ports:
      - "8000:8080"
    volumes:
      - "../build/api-spec/openapi3.yaml:/usr/share/nginx/html/openapi.yaml"
    environment:
      - URL=./openapi.yaml

이후 문제점

일단 이런 방식으로 Spring REST docs 기반 swagger 문서를 만들었다. openapi3.yaml 문서를 통해서 postman에서도 API를 실행할 수 있는 이 확장성이 마음에 들었다.

하지만 현재로서는 해결하지 못한 문제가 있다.

1. docker 컨테이너

도커 컨테이너 환경에서 localhost는 swagger서버를 가리키기 때문에 발생한다.
host 설정을 통해서 로컬에서 접근할 수 있도록 변경하여 해결할 생각이다.

2. cors

spring server는 API 만 제공하기 때문에 cors를 허용해도 무관하다고 판단했다.
설정을 변경하여 해결할 생각이다.

3. 오픈소스

결과는 만족스럽지만 하나 걱정되는 것은 오픈 소스를 활용했다는 것이다. 해당 프로젝트가 거대한 프로젝트라고 하기에는 아직 규모가 작아 보였기 때문에 언제까지 지원을 할지는 미지수다.

 

TMI

오픈 소스의 컨트리뷰터 중에서 한국인을 발견했다. 이분은 SKT에 재직 중인 분인 것 같다. 우연히 알게 된 프로젝트에서 한국인을 발견하니까 신기하고 대단해 보였다.