API를 제공하면서 부족한 문서 품질은 사용자가 원하는 기능을 쉽게 찾을 수 없고 결국에는 API 채택에 영향을 미칩니다.
OAS(Open API Specification)나 AsyncAPI specification 기반으로 만드는 문서는 사용자가 빵을 만들 수 있는 각각의 재료만 제공할 뿐 어떻게 만들어야 하는지 구체적인 레시피를 제공하지는 않습니다. 실제 사용자가 원하는 작업을 진행하기 위해서는 여러 API를 필요와 순서에 따라 사용해야 하는데(레시피) 이런 가이드가 부족하다는 이야기입니다.
이러한 레시피를 포함해 API를 사용할 때 고려해야 할 여러 가지 요소가 사용자뿐 아니라 AI에게도 중요한 요소입니다. 사용자가 겪는 어려움을 AI도 겪을 수 있다는 이야기입니다.
간단한 데모를 진행합니다. 애완동물 입양 서비스를 제공하는 API를 만들고 Workflows 스펙이 이를 어떻게 사용하는지 보여줍니다. API 구성과 Workflows 스펙 코드는 아래 링크에서 확인할 수 있습니다.
https://swagger.io/blog/meet-the-new-api-workflows-specification/
영상에서는 추가적으로 API 엔드포인트를 AI(Workflows 스펙을 학습한 GPTs)에게 던져주고 4개의 단계를 알려준 다음 Workflows Specification을 작성하도록 했습니다. 추가적인 약간의 지시만으로 정확한 yaml 코드가 만들어졌고, 이 코드를 기반으로 다이어그램이 포함된 시작하기 문서를 만들었습니다. 그렇게 만들어진 문서가 아래 링크입니다. API 목록을 그냥 나열한 문서가 아니라 사용자가 원하는 작업을 어떻게 진행하는지 명확하게 설명해 주는 문서가 만들어진 것입니다. 물론, 문서를 만들지 않고 그냥 AI가 Workflows 스펙을 학습한 상태에서 사용자와 대화를 통해 원하는 코드를 만들어주는 것도 가능하겠죠.
https://frankkilcommins.portal.swaggerhub.com/pet-adoptions/docs/getting-started-with-pet-adoptions
발표 당시에는 아직 이름이 정해지지 않아 Workflows 스펙이라고 이야기했는데 지금은 Arazzo Specification이라는 이름이 붙었습니다. Arazzo는 태피스트리(tapestry)를 의미하는 이탈리아어인데 "여러 개의 API 호출을 직물처럼 엮어 복잡한 워크플로우를 구성한다는 개념"을 담아 붙인 이름이라고 합니다.
https://github.com/OAI/Arazzo-Specification
https://spec.openapis.org/arazzo/latest.html
swagger이나 redocly 등에서도 Arazzo에 대한 추가적인 정보를 찾아볼 수 있습니다.
https://swagger.io/blog/the-arazzo-specification-a-deep-dive/
https://redocly.com/learn/arazzo/what-is-arazzo
* 국내 페이먼트 API 문서를 보면 카카오페이 같은 경우에는 각 주제에 "이해하기"라는 챕터를 두고 있습니다. 각 API가 어떤 흐름에 따라 동작해야 하는지 한눈에 볼 수 있도록 제공하는 것입니다. 다른 조직의 문서를 보면 예시를 들어 쉽게 설명하고 있지만 개별 API에 대한 내용만 있고 전체적인 흐름을 알 수는 없습니다.
https://developers.kakaopay.com/docs/payment/online/common
https://youtu.be/mOmivntQaeY?si=5-ECtmgE75eGHc4U
