이번 기록에서는 REST API 문서를 집중적으로 다뤄보겠습니다.
REST API를 제공하는 쪽에서는 사용자가 쉽게 API를 사용할 수 있도록 해야합니다.
- Resources: 노출되고 있는 여러 리소스가 무엇인지 알아야 합니다.
- Action: 수행되는 여러 작업에 대해서도 파악해야 합니다.
- Request/Response Structure (Constraints/Validations): 요청 및 응답 구조는 물론 요청 형식도 알아야 합니다. 사용자가 원하는 응답은 무엇인지, 제약이나 검증은 있는지 따져봐야 합니다.
REST API는 항상 정확해야합니다. 문서는 코드와 동기화되지 않을 수 있기 때문에 항상 신경을 써야합니다.
또 중요한 점은 문서의 일관성입니다. 기업에는 수백개의 REST API가 있을 수 있습니다. 이 모든 API의 문서가 일관된 형식으로 이루어져 있는지 어떻게 알 수 있을까요?
REST API를 관리할 때는 두 가지 옵셥이 있습니다.
- 문서를 수동으로 관리
- 코드에서 문서를 생성하는 방법
이번 기록에서는 코드에서 REST API에 대한 문서를 생성하는 방법에 대해 알아보겠습니다.
API 문서를 다룰 때 이해하고 있어야 할 주용한 2가지 용어가 있습니다.
- Swagger
- 오픈 API
