GraphQL을 사용하면 Introspection을 활용하면 API 문서를 자동으로 생성할 수 있습니다. 하지만 기본 제공되는 문서화 기능만으로는 독자가 맥락을 파악하고 손쉽게 원하는 정보를 얻을 수 없습니다. 때문에 다양한 도구를 사용해서 독자가 정보를 탐색할 수 있게 합니다.
테크니컬 라이터가 별도의 기술 지원을 받지 않고도 GraphQL Playground나 GraphiQL 같은 것을 사용해 기본 문서에 인터랙티브한 기능을 더하고 독자들에게 필요한 정보를 제공할 수 있습니다.
모범적인 사례로 shopify를 보여줍니다(아마 shopify는 자체 개발을 통해 기능을 구현한 것으로 보입니다. 뒤에서 설명하는 발표자의 highnote 사례와는 좀 다릅니다).
shopify의 경우 API를 한 페이지에 길게 나열하지 않고 사용자가 직관적으로 인지할 수 있는 카테고리로 기능을 나누고 항목 선택 시 해당 API만 표시될 수 있도록 구현했습니다.
https://shopify.dev/docs/api/admin-graphql
https://shopify.dev/docs/api/admin-graphql/2024-10/mutations/cartTransformCreate
그리고 모든 API 항목은 코드 예제를 제공하는데 항목에 따라 상황별 코드 예제를 제공하는 경우도 있습니다.
https://shopify.dev/docs/api/admin-graphql/2024-10/mutations/appSubscriptionCreate
오브젝트 항목의 경우 관계를 도식화해서 보여줄 수도 있습니다.
https://shopify.dev/docs/api/admin-graphql/2024-10/objects/CartTransform
highnote의 경우에는 API 레퍼런스는 페이지에 나열하는 형식으로 제공하고 API Explorer를 별도 제공합니다. 현재는 로그인 사용자만 이용할 수 있게 허용하고 있습니다.
* 국내에서도 GraphQL을 도입한 기업이 꽤 많습니다. 아마 목록에 잡히지 않는 케이스가 더 많겠죠.
https://www.codenary.co.kr/techstack/detail/graphql
카카오 스타일 같은 경우 문서를 확인해볼 수 있습니다. Docusaurus를 사용하고 있네요.
2023년 공개된 블로그 게시물에서 GraphQL 문서화 관련해서 살짝 언급이 되고 있습니다.
https://zigzag.kr/_openapi/docs/
https://devblog.kakaostyle.com/ko/2023-07-17-1-msk-mock-in-storybook/
https://youtu.be/V6fs9yQuUN4?si=1IFbOLL4ayAn_30H
GraphQL Docs Beyond the Schema
www.flickr.com
