15. Spring REST Docs

API (Application Programming Interface)

: 대부분 Server-Side (Back-end) 에서 제공되며, 데이터의 조작 (CRUD) 를 하기 위한 기술이다.

 

 

# API 문서를 왜 만들어야 할까?

• '제공자' ↔ '사용자' 사용방법 공유/협의
• API 버전 및 변경사항 관리

# 현업에서 운영하는 API 문서화

• File (Word, Excel...)
• Wiki (Web)
• 그 외

# 기존 방식의 단점

• 버전 변경 등 수정에 취약
• API 와 문서 상태가 다를 수 있음 (버전, 오류 등)
• 검증되지 못한 문서

 

Spring REST(Representational State Transfer) Docs 

• RESTful 서비스에 대한 정확하고 읽기 쉬운 문서를 생성하도록 돕는 것이 목적이다.
• 테스트를 통하여 API 문서를 생성한다.
• 스니펫 (Snippets) 의 조합으로 API 문서를 커스터마이징한다.
• 간결한 적용, 다양한 생성 방법이 있다.

(※ REST : 자원을 이름으로 구분하여 해당 자원의 상태 즉, 정보를 주고 받는 것. 기본적으로 웹의 기술과 HTTP 프로토콜을 활용하기 때문에 웹의 장점을 활용할 수 있는 아키텍처 스타일이다. 네트워크에서 클라이언트와 서버 사이에 통신 방식 중 하나이다.)

 

# Spring REST Docs 의 장점

• 별도의 HTML, PDF 파일로 API 문서를 자동으로 생성할 수 있다. (Hosting 이 가능하다.)
• Request/Response 테스트를 통하여 API 문서의 신뢰도를 상승시킬 수 있다.
• API 변경에 따른 API 문서 최신화를 보장한다.

 

Spring REST Docs VS Swagger

 

# Swagger : 

API 문서화의 양대산맥 중 하나로서, RESTful 문서에 대한 명세보다는 API 를 쉽게 호출해볼 수 있다는 것에 초점이 있다.

 

Spring REST Docs	Swagger
- 테스트를 기반으로 실행 - 문서에 대한 신뢰성 - Product 코드에 영향이 없음 - 간결 + 명료 - Snippets 조합으로 커스터마이징이 가능	- API 테스트 UI 제공 - Annotation 을 통한 간단한 작업 - 테스트 코드가 없어도 문서화 가능 - UI 가 더 예쁨

---

출처 : https://fastcampus.co.kr/courses/204729/clips/

패스트캠퍼스 온라인 강의 - 스프링 아카데미아 15개 영상강의 코스(5월)