[1] Spring REST Docs 이용해 API 문서 작성하기

안녕하세요.

이 글은 제가 서버 개발자로 일하며 회사내 동료, 외부 업체 등에 Open API 형태로 API 문서를 제공했던 경험들을 공유 합니다.

 

1. Swgger가 있잖아요 ?

먼저 Swagger 이야기를 해볼게요.

Swagger를 사용했을때 단점은 다음과 같았습니다.

 

비즈니스 코드 곳곳에 어노테이션을 추가해야 합니다.

이러다 보니 문서를 위한 어노테이션 및 주석을 달아야 하고 해당 어노테이션이 추가될때마다

관리도 되지 않고 문서를 위한 작업을 해야했습니다.

보는 사람에 따라 코드 가독성이 떨어지기도 합니다. 저의 경우 그랬습니다.

 

하지만 가장 좋지 않다고 생각했던것은,

예전에 API의 A값의 의미는 "a" 였는데 개발을 진행하다보니 혹은 릴리즈를 하다보니 "b"로 바뀌는 경우

해당 어노테이션을 수정해줘야 합니다.

이런일이 많지 않았지만 반복되다보면 문서를 위한 작업을 해야하고 결국 동기화가 되지 않기 시작합니다.

문서를 읽는 사람은 구현 내용과 설명이 달라 신뢰를 잃게되고

문서를 작성하는 사람은 부담감이 점차 커져 갑니다.

저는 그래서 다른 방법을 찾기 시작했습니다.

2. 그럼 Spring REST Docs 은 뭐가 좋은가?

먼저 Spring REST Docs로 작성된 문서의 결과물 부터 보겠습니다.

Spring RestDoc로 작성된 문서 결과물

 

 

Spring RestDoc로 작성된 문서 결과물

 

위 문서는 JWT 토큰 기반 인증서버의 설계 사항과 API 사용법을 작성한 결과물 입니다.

OpenAPI 형태로 제공되지 않아 문서의 일부 내용은 제 블로그 주소로 변경했습니다.

 

문서 작성을 위해 다음의 목표가 충족하는지 검토 했습니다.

 

1. TDD 기반과 잘 어울릴 것

현재 서비스, 컨트롤러 레이어 두곳 모두 테스트 케이스를 작성하고 있습니다.

위 문서는 Junit4를 이용한 컨트롤러 테스트 케이스 결과물을 Spring RestDoc을 이용해 문서화한 결과물 입니다.

따라서 테스트케이스가 변경될 때 마다 문서도 지속적으로 변경됩니다.

또한 실제 payload 를 작성해야만 테스트케이스가 통과되기 때문에 문서 작성을 위해 의미없는 1111 2222 등을 넣어

문서를 대충 작성하는 일도 없게 됩니다.

 

2. 문서를 위한 문서를 쓰지 말 것

테스트 케이스만 잘 작성해 두면 요구사항에 따라 테스트케이스를 수정하고 빌드된 결과물과 함께 문서또한 갱신되므로

문서를 위한 문서를 작성하지 않아도 됩니다.

 

빌드 결과물로 api-guide.html이 생성 됩니다.

위와 같이 빌드의 결과물로 api-guide.html이 생성됩니다.

 

3. 문서를 읽는 사람이 API 규격에 대해 명확하게 파악하고 개발 할 수 있을 것

 

adoc 파일 목록

테스트 케이스 성공시 generated-docs하위에 작성한 테스트 케이스 목록으로 폴더가 생성되고 최 하위에 adoc파일이 생성됩니다.

해당 파일의 내용은 다음과 같습니다.

[source,http,options="nowrap"]
----
GET /api/v1/accounts HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0dGMiOiJhYyIsImR0YyI6Im1hIiwiZXhwIjoxNjQ2MzEwMzc0LCJyaWMiOjMsImlhdCI6MTY0NjMwNjc3NH0.ddRITM_6RCLS8tRXf5J10wO06n-bVP05AC4yX-oySTA
Accept: application/json
Host: api-address

----

파일 목록을 보면 http request, header, body, response, curl 등으로 세분화 되어 있고

위 파일들을 이용해 API명세에 대해 세부적으로 명세 할 수 있게 됩니다.

따라서 API 사용자가 보다 더 API에 대해 이해 할 수 있게 됩니다.

 

4. 개발 시간을 빼앗기지 말 것

개발할 시간도 부족하고 회의도 해야하고 문서도 작성해야 하고 바쁜 회사생활에 반복되는 일은 최대한 자동화 하는것이 좋습니다.

개발 문서또한 개발보다 더 중요한 작업이지만 시간 할애를 줄일수 있으므로 개발에 좀 더 시간을 할애 할 수 있습니다.

 

5. 개발을 진행하며 추가된 API 에 대해 JIRA등에 링크로 해당 API 사용 명세를 공유 할 수 있을 것

하나의 개발 이슈 또는 추가 구현 사항이 있을때 다음과 같은 프로세스로 일 하고 있습니다.

 

[이슈사항 또는 구현 사항 JIRA 생성] -> [담당자 할당] -> [명세 작성] -> [github에 jira 번호로 브랜치 생성]

-> [개발 진행] -> [코드리뷰] -> [merge] -> [테스트 및 구현 확인] -> [이슈 close]

 

위 단계중 [개발 진행] 단계에서 서버의 API를 사용하는 여러 개발자 분들께 문서의 링크를 댓글로 노티할 경우 보다 의사소통에 수월해 짐을 느꼈습니다.

 

 

3. Spring RestDoc 문서 작성에 필요한 사전 사항

저의 경우 아래를 사용하여 개발 및 문서를 작성하고 있습니다.

SpringBoot, JUnit4, MocMvc, AsciiDoc, Maven

 

이 중 AWS 환경에 디펜던시가 있는 여러 서비스들 이를테면 s3같은 경우등은 Mocking해야 하므로 서비스 레이어는 대부분 Mocking 처리 하고 있습니다.

이 외에도 실제 서버는 프라이빗 망 안에서 돌아가 문서 빌드된 내용과 header값 등을 수정할 필요가 있었는데 이러한 세세한 것들에 대한 수정도 필요합니다.

 

다음 글에서는 실제 코드와 함께 문서 작성 법에 대해 기술해 보겠습니다.