API 문서 도구

1. API란?

• 응용 프로그램에서 사용할 수 있도록, 운영 체제나 프로그래밍 언어가 제공하는 기능을 제어할 수 있게 만든 인터페이스를 의미한다.

2. API 문서화 도구

1) Swagger

• 개발자가 REST 웹 서비스를 설계, 빌드, 문서화, 소비하는 일을 도와주는 대형 도구 생태계의 지원을 받는 오픈 소스 소프트웨어 프레임워크이다.

자바 개발에서 많이 사용하는 도구이며 Gradle과 같은 빌드 도구에서 의존성 추가 후 간단한 세팅만 해주면 Annotation으로 문서를 만들 수 있다.

2) Gitbook

• 협업을 위한 문서 작성 플랫폼으로 업무 가이드라인, API 명세서 작성 등의 기본 기능을 제공합니다. Git 형식의 협업 및 버전 관리를 지원합니다.

API 문서화를 API 구현 전에 작성할 수 있으며, API에 대한 설명을 구체적으로 작성할 수 있다. 뿐만 아니라 다양한 템플릿을 가지고 있으며, Slack 알림 등과 같은 편리한 기능을 가지고 있다.

3) Postman

• 개발자들이 API를 디자인하고 빌드하고 테스트하고 반복하기 위한 API 플랫폼이다.

API에 대한 설명을 구체적으로 작성할 수 있고, 이 또한 API를 구현하기 전에 작성할 수 있다. 뿐만 아니라 여러가지 상황의 API 요청과 응답 예시를 직접 작성하거나 저장하여 사용이 가능하다.

3. 개인적인 생각

• API 문서화 도구에는 이 외에도 다양한 도구들이 있다. 하지만 각 도구마다 장단점이 존재한다. 그런 부분과 상황을 잘 고려하여 각 API 문서화 도구를 유연하게 사용해 보는 것이 좋을 것 같다.

---

참조

https://swagger.io/tools/swagger-ui/
https://docs.gitbook.com/content-editor/blocks/openapi
https://learning.postman.com/docs/publishing-your-api/documenting-your-api/#edit-api-documentation