API문서화 자동화를 위한 RestDocs 적용

[minseongkimdev]

개요

AS-IS

• API에 대한 문서가 없어 다른 사람이 작성한 API에 대한 스펙을 알 수 없고 이를 알기 위한 추가적인 커뮤니케이션 비용이 발생합니다.
• 일일이 API에 대한 명세를 작성할 수 있겠지만 이를 자동화하는 것이 좋아보입니다.

TO-BE

• RestDocs를 활용하여 API 문서화를 자동화합니다.

진행상황

• 1. Gradle에 RestDocs관련 라이브러리 추가
• 2. UserController 통합 테스트에 RestDocs에 필요한 요청, 응답 정보 기술
• 3. AsciiDocs을 통한 API문서 마크업

RestDocs 참고사항

• 모든 테스트가 성공해야만 API 문서 파일이 생성됩니다.
• ./gradlew build 을 통해 API 문서 파일을 생성할 수 있습니다.
• AsciiDoc, RestDocs, 우아한형제들 기술블로그 추후 작업하는데 도움이 될만한 레퍼런스입니다.

문서화 양식

• 크게 프로젝트의 개요와 REST API 명세부로 나눴습니다. (추후에 필요한 섹션은 추가될 수 있습니다.)
• 우선 요청 성공에 대한 케이스만 명세하였습니다.
• 요청 파라미터 or 필드, 요청 방법, 응답(성공시) 순으로 명세하였습니다.