API 문서화에 대한 이야기

[Choi-JJunho]

주제

친애하는 백엔드 여러분들께... @rawfishthelgh @yeonkkk @Kim0914

현재 팀 내에서 Notion으로 API 명세를 수행하고 있습니다.

이러한 방식이 팀원간의 생각을 동기화 시키는데는 도움은 되지만 API를 확인할 때 마다 Notion에 접속한다는 부분에서 접근성이 다소 떨어질 수도 있다는 생각이 들었습니다.

또한 백엔드에서 개발이 완료된 API의 명세가 Notion에 작성된 내용과 명확하게 일치하는지도 신뢰할 수 없다는 생각도 들었습니다.

+) 8월 4일 추가

구체적인 예시로 다음과 같이 수작업으로 이뤄진 문서에 대한 신뢰도가 대폭 하락할 수 있다는 사례도 존재합니다.

클라이언트(프론트엔드)에서 신뢰할 수 있는 문서를 제공하기 위해 실제 코드로부터 작성되는 문서화의 필요성을 느꼈고 이에 다음과 같은 두가지 방안을 제시하고자합니다.

요약 : API 문서화를 위한 도구 선택

1. Spring RestDocs를 이용한 방식

Spring Rest Docs는 Spring에서 제공하는 문서화 도구입니다.
테스트를 통해 도출된 결과를 문서로 작성하며 프로덕션 코드에 영향이 없다는 특징이 있습니다

실제 적용사례는 아래 블로그를 참고해주세요

• 우아한 기술블로그 - Spring Rest Docs 적용
• 우테코 달록 팀블로그 - Spring REST Docs를 사용한 API 문서 자동화

예시입니다

2. Swagger를 이용한 방식

Swagger는 API 문서화를 돕는 오픈소스 도구입니다.
RestDocs보다 비교적 설정이 간편하다는 장점이 있으며 문서화에 있어 테스트에 구애받지 않는다는 특징이 있습니다.

또한 실제 API를 호출한다는 특징이 있으며 프로덕션 코드에 문서화와 관련된 코드가 포함된다는 특징도 존재합니다.

// Request DTO 예시
@Getter
@Builder
@AllArgsConstructor
@NoArgsConstructor
public class CreateBoard {

    @NotNull
    @ApiModelProperty(notes = "게시판 제목", example = "자유게시판", required = true)
    private String title;

    @ApiModelProperty(notes = "게시판 설명", example = "자유롭게 글을 올리는 게시판입니다.")
    private String description;
}

Swagger 사용 시 다음과 같은 화면을 기대할 수 있으며 실제 API 요청과 응답을 확인할 수 있습니다.

[Choi-JJunho]

저는 RestDocs를 사용하고싶습니다.
문서화를 위해 테스트를 강제함으로써 보다 신뢰도 높은 API를 배포할 수 있는 것 같습니다.

[Kim0914]

저는 둘 중 어느 것을 사용해도 크게 상관없을 것 같습니다.

Rest docs의 경우 테스트코드를 추가적으로 작성하고 adoc을 연결시켜야하는 작업이 필요하지만, 통과된 테스트코드를 기반으로 문서화할 수 있는 점이 장점이라고 생각합니다.

Swagger의 경우 테스트코드를 작성하지 않고 관련 어노테이션을 기반으로 쉽게 작성할 수 있다는 장점이 있지만, 테스트 코드 동작과는 별개이기 때문에 신뢰도가 떨어질 수 있다는 생각이 듭니다. 또한 프로덕션 코드에 어노테이션을 달아야하는 단점도 있죠. 다만 Swagger의 경우 인증이 필요한 api 요청을 쉽게 보낼 수 있고, 클라이언트가 바로 테스트 해볼 수 있다는 추가적인 장점이 있습니다.

다른 분들의 의견을 듣고 다수가 선택하는 방향으로 따라가겠습니다 ㅎㅎ

[yeonkkk]

저는 RestDocs 를 사용하면 좋을 것 같아요.
Swagger는 상대적으로 설정이 간편하지만, 프로덕션 코드과 함께 작성해야 해서 swagger관련 코드가 들어가게 되면 지저분하고 가독성을 해칠수도 있을 것 같네요.

저희가 지금도 기능 개발 시 테스트 코드도 함께 작성 하고 있기 때문에, RestDocs를 사용해도 큰 문제 없을 것 같아요!
무엇보다 지금보다 테스트를 더 꼼꼼하게 작성해야한다는 장점도 있겠어요~~
이미 많은 기능들을 구현했기 때문에 시간적으로 쫓기는 것도 아니고요!

RestDocs 공부해서 적용해보고 싶습니다😀

[WaiNaat]

저는 둘 다 좋은데요?
둘 다 예시가 있고 각 항목의 타입을 알 수 있어서 불편하지 않다고 느꼈어요
백엔드 분들이 더 편하다고 생각하거나 해보고 싶은 걸로 가도 될 것 같습니다

[rawfishthelgh]

저는 Swagger에 한 표 입니다.
테스트 코드를 통해 api 요청을 테스트하려면 테스트 코드를 짜는 시간 리소스가 많이 들게 됩니다.
(주노가 인수 테스트 짜느라 고생했던 것 처럼...)
Swagger를 사용하면 클라이언트 api요청 테스트를 더 빠르게 테스트할 수 있어
"더 많은 테스트가 가능하다" 라는 이점을 살려 오히려 신뢰성을 높일 수도 있다고 봅니다.

[Choi-JJunho]

그렇다면 RestDocs 사용으로 결정짓겠습니다 (땅땅땅)