[유지보수] API 문서

[rhakdnj]

서버는 사용자에게 API 문서를 통해 어떻게 사용할지 명세를 제공합니다.
API 명세서에 따라 사용자는 해당 서버에 요청을 남깁니다.

1. API 명세서는 코드와 항상 동기화되어야 합니다.
2. API 명세서는 하나의 프로덕트의 문서화, 그 자체 입니다. 이를 이용해 커뮤니케이션, 협업을 할 수 있습니다.

springdoc-openapi-webmvc-ui 와 같은 라이브러리를 통해 코트를 통해 API 명세서가 자동 생성하여 관리할 수 있습니다.

그렇다면 1번 조건인 명세서와 동기화는 문제가 해결될 수 있습니다. 다만 API Spec에 대한 자세한 설명은 한계가 있습니다. 이와 더불어 yaml 문법을 통해 API문서를 재사용할 수 있는 측면 또한 강점이 있습니다.

제가 FE팀 혹은 해당 API를 사용하는 사용자라면 자세한 API 명세서를 필요로 한다고 판단하여, 분리하려고 합니다.

참조

https://redocly.com/docs

• [ ] prefer header - rfc-7240
• [ ] Etag - rfc-7232