57.01_[Spring MVC] API 문서화_ API 문서화_22.11.11

>API 문서화
: 해당 애플리케이션의 API를 사용할 방법을 문서로 만든것.
: 물론 수기로도 가능하지만 너무나도 비용이 많이 들고 오차 가능성 때문에 권하지는 않음.
: 때문에 Java 에서 사용할 수 있는 자동 API 문서화 툴이 존재하고, 대표적으로 Spring Rest Docs, Swagger이 있음.

>API 문서화 방식 종류
-Swagger
: 다양한 애너테이션을 붙이며 해당 부분이 어떻게 문서화될지를 표현한다.
: 문서화시킬 부분에 애너테이션을 붙이면 되는 것이라서 따로 테스트를 할 필요가 없다. (테스트 케이스를 작성하기 싫어하는 개발자에게 추천)
: 그리고 Postman처럼 API 요청 툴로써 기능할 수 있는 장점이 있다.
: 하지만 코드에 애너테이션이 과하게 붙기 때문에 오히려 개발자가 코드를 보기 힘들어지는 단점이 있다.
-Spring Rest Docs
: 테스트 케이스 내부에 API 문서화 작성 코드를 심는 것이 Spring Rest Docs 의 큰 특징이다.
: 그렇기 때문에 테스트가 통과해야만 API 문서화 작성 코드가 실행된다. 즉, 테스트가 실패하면 API 문서화가 되지 않는다.
: 테스트를 꼭 해야만 하고, API를 호출하는 툴의 역할을 할 수 없다는 단점이 있다.
: 하지만 테스트에 익숙해지는 것이 좋기도하고, API 문서 자체로의 기능은 충분하다. 그리고 테스트가 통과된 상태로 문서화가 되는 것이기 때문에 API 스펙 정보와 API 문서 정보가 불일치로 발생할 문제를 예방할 수 있다.