API 문서는 가독성이 좋아야 하며 파편화는 피하자는 생각이 최근에 들었고 관련해 적어본 글이다.
정보를 제공하는 모든 문서는 독자의 추가적인 의문을 적게 만들어야 한다. 만약 A 서비스를 연동하기 위해 A 서비스의 API 문서를 본다고 하자. 요청 파라미터, 응답 바디, 에러메세지 등이 어떠한지 충분할 설명이 있다면 추가적인 소통없이 연동을 진행하면 된다. 소통 비용을 줄일 수 있다는 점은 문서 작성자와 문서 독자 모두에게 적용되는 장점이다. 최근에 알리페이의 API 문서를 보니 가독성이 좋다고 느꼈다. 나도 이러한 문서를 만들 수 있게 고민해봐야지.
MSA 환경에서는 여러 서비스가 잘게 나눠지기 때문에 API문서도 파편화가 된다. 우리 팀은 관리하는 프로젝트가 10개 이상인데, 하나 프로젝트에도 여러 모듈로 나눠진다. 각 모듈은 고유한 도메인을 가지고 있기 때문에 API 문서도 많이 생성된다. 이럴 경우 팀 내에서도 API문서가 어디 위치하는지 파악을 못하는 경우도 생긴다. 그러다보니 파편화된 API문서를 한번에 관리될 수 있는 방안이 무엇일까 고민이 들었다. 라인의 모두가 행복해지는 API 문서 통합과 자동화 블로그 글도 도움이 됐다.
API 문서는 가독성이 좋아야 하며 파편화는 피하자는 생각이 최근에 들었고 관련해 적어본 글이다.
정보를 제공하는 모든 문서는 독자의 추가적인 의문을 적게 만들어야 한다. 만약 A 서비스를 연동하기 위해 A 서비스의 API 문서를 본다고 하자. 요청 파라미터, 응답 바디, 에러메세지 등이 어떠한지 충분할 설명이 있다면 추가적인 소통 없이 연동을 진행하면 된다. 소통 비용을 줄일 수 있다는 점은 문서 작성자와 문서 독자 모두에게 적용되는 장점이다. 최근에 알리페이의 API 문서를 보니 가독성이 좋다고 느꼈다. 나도 이러한 문서를 만들 수 있게 고민해봐야지.
MSA 환경에서는 여러 서비스가 잘게 나뉘기 때문에 API 문서도 파편화가 된다. 우리 팀은 관리하는 프로젝트가 10개 이상인데, 하나 프로젝트에도 여러 모듈로 나뉜다. 각 모듈은 고유한 도메인을 가지고 있기 때문에 API 문서도 많이 생성된다. 이러면 팀 내에서도 API 문서가 어디 위치하는지 파악을 못 하는 경우도 생긴다. 그러다 보니 파편화된 API 문서를 한 번에 관리할 방안이 무엇일까 고민이 들었다. 라인의 모두가 행복해지는 API 문서 통합과 자동화 블로그 글도 도움이 됐다.