[Spring MVC][API 문서화]

학습 목표

• API 문서화가 왜 필요한지 이해할 수 있다.

API 문서화란

API 문서화란 클라이언트가 REST API 백엔드 애플리케이션에 요청을 전송하기 위해서 알아야 되는 요청 정보(요청URL(또는URI), request body, query parameter 등)를 문서로 정리한 것을 의미한다

API사용을 위한 어떤 정보가 담겨 있는 문서를 API문서 또는 API 스펙(사양)이라고 한다

API문서는 개발자가 요청 URL&URI 등의 API 정보를 직접 수기로 작성할 수도 있고 애플리케이션 빌드를 통해 API 문서를 자동 생성할 수도있다.

API 문서 생성의 자동화가 필요한 이유

한번 작성된 API 문서에 기능이 추가되거나 수정되면 API 문서 역시 함께 수정되어야 하는데 update를 못한경우 클라이언트에게 제공된 API 정보와 수기로 작성한 정보가 다를수 있으므로 자동화가 필요하다.

• Spring Rest Docs와 Swagger의 차이점

• Swagger의 API 문서화방식
  Java 기반의 애플리케이션에서는 전통적으로 Swagger라는 API 문서 자동화 오픈 소스를 많이 사용해 왔다.

Swagger API 문서 화면 예

Postman에서 MemberController에 HTTP요청을 전송하듯 [Execute]버튼을 누르면 MemberController에 요청을 전송할 수 있다.

Postman처럼 API 요청 툴로써의 기능을 사용할 수 있다는 것이 Swagger의 대표적인 장점이다.

• Spring Rest Docs의 API 문서화 방식

Spring Rest Docs와 Swagger의 차이점은 Spring Rest Docs의 경우 애플리케이션 기능 구현과 관련된 코드에는 API 문서 생성을 위한 애너테이션 같은 어떠한 정보도 추가되지 않는다. 대신 슬라이드 테스트를 위한 테스트 클래스에 API문서를 위한 정보가 추가된다.

Spring Rest Docs로 생성된 API 문서

장점은 테스트 케이스에서 전송하는 API 문서 정보와 Controller에서 구현한 Request Body, Response Body, Query Parmeter 등의 정보가 하나라도 일치하지 않으면 테스트 케이스의 실행 결과가 "failed"되면서 API 문서가 정상적으로 생성되지 않는다는 것이다 즉 테스트 케이스의 실행 결과를 "passed"로 만들지 않으면 API문서 생성이 완료되지 않는다. 달리 표현하자면 , 테스트 케이스의 실행 결과가 "passed"이면 Controller에 정의되어 있는 Request Body나 Response Body 등의 API 스펙 정보와 일치하는 API 문서가 만들어진다단점으로는 테스트 케이스를 일일이 작성해야 되고, Controller에 대한 모든 테스트 케이스를 "passed"로 만들어야 한다는 점이다

 

	Spring Rest	Rest DocsSwagger
장점	제품코드에 영향 없다.	API 를 테스트 해 볼수 있는 화면을 제공한다.
	테스트가 성공해야 문서작성된다.	적용하기 쉽다.
단점	적용하기 어렵다.	제품코드에 어노테이션 추가해야한다.
		제품코드와 동기화가 안될수 있다.

 

Point

• API 문서화란 클라이언트가 REST API 백엔드 애플리케이션에 요청을 전송하기 위해서 알아야 되는 요청 정보(요청 URL(또는 URI), request body, query parameter 등)를 문서로 잘 정리하는 것을 의미한다.
• API 사용을 위한 어떤 정보가 담겨 있는 문서를 API 문서 또는 API 스펙(사양, Specification)이라고 한다.
• API 문서 생성의 자동화가 필요한 이유
  • API 문서를 수기로 직접 작성하는 것은 너무 비효율적이다.
  • API 문서에 기능이 추가되거나 수정되면 API 문서 역시 함께 수정되어야 하는데, API 문서를 수기로 작성하면 API 문서에 추가된 기능을 빠뜨릴수도 있고, 클라이언트에게 제공된 API 정보와 수기로 작성한 API 문서의 정보가 다를수도 있다.

• Swagger의 API 문서화 방식
  • 애터네이션 기반의 API 문서화 방식
  • 애플리케이션 코드에 문서화를 위한 애너테이션들이 포함된다.
  • 가독성 및 유지 보수성이 떨어진다.
  • API 문서와 API 코드 간의 정보 불일치 문제가 발생할 수 있다.
  • API 툴로써의 기능을 활용할 수 있다.
• Spring Rest Docs의 API 문서화 방식
  • 테스트 코드 기반의 API 문서화 방식
  • 애플리케이션 코드에 문서화를 위한 정보들이 포함되지 않는다.
  • 테스트 케이스의 실행이 “passed”여야 API 문서가 생성된다.
  • 테스트 케이스를 반드시 작성해야된다.
  • API 툴로써의 기능은 제공하지 않는다.