API 명세서 작성

Album 프로젝트 전의 프로젝트들을 진행할 때는 API 명세서를 구글 독스, 노션 등에 직접 작성하였다.

 

사람이 API 명세서를 직접 작성하다보니, 오타나 특정 내용을 누락하는 경우가 꽤 있었다.

그리고 명세서 유지 보수 측면에서도 꽤 비효율적이었다.

 

그래서 Album 프로젝트에서는 어플리케이션을 통해 API를 자동으로 생성하는 방법을 사용하고자 하였다.

스프링 어플리케이션의 대표적인 API 작성 방법으로는 Spring Rest Docs와 Swagger가 있었고, 장단점 비교를 통해 적절한 방법을 선택하고자 하였다.

 

비교

Spring Rest Docs

Spring Rest Docs의 가장 큰 장점은 서비스 코드에 불필요한 영향을 주지 않는다는 것이다.

또한 API 명세서가 작성되기 전에 테스트가 성공적으로 수행되어야 하기 때문에, 작성되는 API 명세서를 신뢰할 수 있다.

 

단점으로는 적용 방법이 상대적으로 어렵다는 것이다.

그리고 API 명세서를 작성하기 위한 테스트 코드를 따로 작성하고 관리해야한다.

Swagger

Swagger의 장점으로는 적용 방법이 상대적으로 간편하며, 별도의 테스트 코드를 관리할 필요가 없다는 것이다.

그리고 API 명세서 상에서 API를 테스트해 볼 수도 있다.

 

단점으로는 서비스 코드가 Swagger 라이브러리에 의존하게 되고, 어노테이션이 추가되는 등 서비스 코드에 영향을 준다는 것이다.

그리고 API 명세서 작성 전에 테스트가 진행되지 않으므로, API 명세서의 정확성을 보장해주지 않는다.

 

결정

나는 API 명세서의 정확성을 보장하고, 서비스 코드에 대한 불필요한 영향을 지양하는 것이 더 큰 가치를 갖는다고 판단하여, Spring Rest Docs를 선택하였다.