당신은 주제를 찾고 있습니까 “api 문서 예시 – 초보 개발자의 좌충우돌 API 문서 만들기“? 다음 카테고리의 웹사이트 th.taphoamini.com 에서 귀하의 모든 질문에 답변해 드립니다: th.taphoamini.com/wiki. 바로 아래에서 답을 찾을 수 있습니다. 작성자 Hanbyul Oh 이(가) 작성한 기사에는 조회수 418회 및 345905 Like 개의 좋아요가 있습니다.
Table of Contents
api 문서 예시 주제에 대한 동영상 보기
여기에서 이 주제에 대한 비디오를 시청하십시오. 주의 깊게 살펴보고 읽고 있는 내용에 대한 피드백을 제공하세요!
d여기에서 초보 개발자의 좌충우돌 API 문서 만들기 – api 문서 예시 주제에 대한 세부정보를 참조하세요
코드스테이츠 Software Engineering Immersive 23th
오한별
Final Project Tech Interview
api 문서 예시 주제에 대한 자세한 내용은 여기를 참조하세요.
API 문서 톺아보기
오늘은 Release Note 톺아보기에 이어 두 번째 시리즈로 API 문서를 샅샅이 톺아보도록 하겠습니다 🙂 … [그림 3] Request Syntax 예시.
Source: tech.kakaoenterprise.com
Date Published: 12/7/2021
View: 7881
문서 엔지니어링과 API 문서화
아래 코드는 소스코드 주석 기반 API 레퍼런스 생성 도구인 자바독의 예시입니다. /** * 내가 만든 정말 멋진 클래스 * @author jeongeun.jeon * @version …
Source: engineering.linecorp.com
Date Published: 10/7/2021
View: 7472
좋은 API 문서 작성 방법 – 개발자 로그
이를 위해 일관적인 문서 구조와 예시를 제공할 필요가 있습니다. 세부 사항으로는 일관적인 헤딩 사용, 하이퍼링크 제공, 문단 나누기 및 리스트 …
Source: walkingplow.tistory.com
Date Published: 2/23/2022
View: 6942
api 문서화, 좋은 예시
1. swagger https://swagger.io/ 이전 회사에서 쓰던 api 문서화 프레임워크. … api 문서화, 좋은 예시 … 문서 작성을 도와주는 툴인듯 하다.
Source: yuda.dev
Date Published: 12/9/2022
View: 5870
[Spring] API 문서작성 툴 고르기
Swagger API 문서 예시 (링크). Swagger는 무료로 제공되고, 문서자체에서 바로 해당 API를 테스트해 볼 수 있다는 점이 마음에 들었다.
Source: learnote-dev.com
Date Published: 5/11/2021
View: 5693
API 문서 도구로 효율적인 문서 만들기 – AppMaster
API 엔드포인트 문서는 어떻게 작성합니까? 5. API 문서 예시란 무엇입니까? API 문서에 가장 많이 사용되는 템플릿은 무엇입니까? 문서화에 가장 적합한 소프트웨어는 …
Source: appmaster.io
Date Published: 9/1/2022
View: 4261
API 문서 작성하는 방법 – 베짱이가 되고 싶은 개미 개발자
이번에 나는 표를 이용하여 작성해보았다. 예시 자료. 마크다운언어로 작성해서 올렸는데 생각보다 썩 이쁘게 나온 거 같지가 않았다.
Source: ant-programmer.tistory.com
Date Published: 2/16/2021
View: 1353
[ API ] 프로젝트 API 문서화 DEVLOG – 와플공장
이전까지는 Backend API 문서를 다른 팀원이 작성하거나 그래픽으로 정리해서 줘본 경험밖에 없어서, 이번 기회에 Swagger를 이용하여 일반에 바로 공개할 …
Source: devwaffle.tistory.com
Date Published: 2/30/2022
View: 2011
API 문서화 공부하기 5 – 매개변수
헤더 매개변수, 경로 매개변수 및 쿼리 문자열 매개변수와 같은 여러 유형의 매개변수가 있다. 매개변수의 예시는 다음과 같다. 토스 페이먼츠에서는 문서 …
Source: jidocument.tistory.com
Date Published: 12/11/2021
View: 2781
주제와 관련된 이미지 api 문서 예시
주제와 관련된 더 많은 사진을 참조하십시오 초보 개발자의 좌충우돌 API 문서 만들기. 댓글에서 더 많은 관련 이미지를 보거나 필요한 경우 더 많은 관련 기사를 볼 수 있습니다.
주제에 대한 기사 평가 api 문서 예시
- Author: Hanbyul Oh
- Views: 조회수 418회
- Likes: 345905 Like
- Date Published: 2020. 12. 18.
- Video Url link: https://www.youtube.com/watch?v=7kj2nj9HCMg
API 문서 톺아보기
시작하며
안녕하세요. 카카오엔터프라이즈 테크니컬라이팅 팀의 Crystal(김유리), Sandy(차신영), July(김정인)입니다.
테크니컬라이팅 팀에서는 Kakao i 기술문서 사이트에 카카오엔터프라이즈가 개발하고 있는 다양한 기술들을 문서를 통해 전달하고 있는데요. 오늘은 Release Note 톺아보기에 이어 두 번째 시리즈로 API 문서를 샅샅이 톺아보도록 하겠습니다 🙂
API(Application Programming Interface)는 ‘서버와 클라이언트가 데이터를 주고 받을 수 있도록 도움을 주는 매개체’라고 정의할 수 있습니다. API를 사용하기 위해서 사용자는 서버와 클라이언트 사이에 존재하는 몇 가지 약속을 따라야는데요. 메시지의 데이터 형식은 무엇이고, 글자수 제한이 있다면 몇 자인지, 어떤 방식으로 데이터가 전달되어야 하는지, 요청에 대한 결과는 어떤 형식으로 확인할 수 있는지 등과 같은 약속들을 예로 들 수 있습니다.
그럼 이 약속들은 어디서 확인할 수 있을까요? 이때 필요한 것이 바로 API 문서입니다. 저희 테크니컬라이팅 팀에서는 API 문서화에 대한 중요성을 인식하고, API 문서화 방법들과 당면한 과제들을 고민하고 있는데요. 오늘은 API 문서의 구성과 좋은 API 문서를 작성하기 위한 방법들을 살펴보도록 하겠습니다.
︱ API 문서 구성
앞서 API 문서는 서버와 클라이언트간 특정 기술을 사용하기 위한 약속이라고 정의했는데요. ‘약속’이라는 개념에만 초점을 맞추다 보면 API 문서는 자칫 기능들만 나열된 API 명세서가 될 수 있습니다. API 문서화에서는 이런 API 명세서와 함께 API가 어떤 동작을 하는지, 어떤 목적에서 API가 탄생했는지, API를 사용하기 전에 수행해야 할 사전 작업이 있는지 등의 충분한 개념 설명이 담긴 ‘개요’와 API 사용 시퀀스를 설명한 ‘시작 가이드’도 준비하는 것이 좋은데요. 회사별 서비스나 기술 특성에 따라 API 문서 구성이나 문서명은 조금씩 다를 수 있지만, 오늘은 일반적으로 통용되는 API 문서 구성을 살펴보도록 하겠습니다.
# 개요
기술 문서의 서론은 독자들에게 본문의 요약, 작성 배경, 관련된 개념 등을 설명해 주는 역할을 합니다. 즉, 서론은 독자에게 글에서 말하고자하는 바를 전달하고, 글을 이해하기 위한 사전 지식 제공 등 독자가 글을 효과적으로 읽을 수 있도록 ‘가이드’하는 역할을 합니다. API 문서에도 이렇게 서론의 역할을 하는 섹션인 개요(Overview)가 필요한데요. 개요에는 API 소개, 개발 배경, 비즈니스 목적 등과 함께 공통 요청(Request) 및 응답(Response) 형식, 공통 에러 타입 등 전반적인 API 소개와 동작 설명을 포함할 수 있습니다.
• API 소개
API는 특정 목적을 가지고 탄생한 기능입니다. 따라서 API에 대한 간략한 소개, 개발 배경, 비즈니스 목적과 API의 장점을 소개하는 것이 좋은데요. 보통 내부 개발자들은 해당 API의 기획부터 개발까지 자세한 내용들을 잘 알고있겠지만, API 문서를 읽는 외부 독자들은 이런 내용을 알 수없습니다. 따라서, 단순히 API에 대한 기능 설명을 하는 것 보다는 API의 개발 배경, 비즈니스 목적, 장점 등을 포함한다면 외부 개발자는 API를 좀 더 명확히 이해하는데 도움이 될 것입니다.
• 공통 요청/응답 형식
개요에는 공통 요청(Request)과 응답(Response) 형식도 포함될 수 있는데요. 일반적으로 한 서비스의 API는 통일된 방식으로 API를 호출하며, 이때 API를 개발자가 어떤 방식으로 개발했느냐에 따라 문서의 구성이 달라집니다. 예를 들어 API 요청을 할 때 사용하는 데이터 형식을 ‘applicatoin/json’으로 제한했거나, 또는 ‘application/x-www-form-urlencode’로 표현된 데이터를 허용하는 개발자도 있는 것이죠.
응답도 마찬가지입니다. 어떤 개발자는 성공 혹은 실패 여부를 success 필드에서 성공인지 실패인지 설명하는 반면, 다른 개발자는 상태 코드를 통해 제공하는 경우도 있죠. 그리고 이런 점은 API 문서에 정확하게 반영되어야 합니다.
이렇게 개요에 해당 API의 공통된 요청과 응답 형식을 정리하면 독자는 API를 어떻게 접근할지 파악할 수 있습니다. 또한 동일한 내용을 각각의 API의 상단에 반복하여 작성하지 않아도 되기 때문에 가독성 있는 문서를 만들 수 있습니다.
• 공통 에러
만약 API 간 공통되는 에러 코드가 존재한다면, 문서의 한 섹션에 에러 코드를 모아두고 관리를 하는 것이 효율적입니다. 혹시 이런 에러 코드를 모아둘 섹션이 마땅치 않다면, 이를 개요 문서에 정리하고 각 API에 공통 에러 테이블을 링크로 연결하는 것은 어떨까요? 문서의 한 섹션에 공통 에러를 제공하면 각 API에 에러 코드를 각각 추가하지 않아도 되고, 변경도 한 곳에만 하면 되니 테크니컬라이터 입장에서는 문서 정합성 유지에도 큰 도움이 됩니다.
# 시작하기
아무리 API 레퍼런스가 잘 작성되었다 할지라도, 해당 API를 어떤 순서로 어떻게 사용하는지를 설명하는 개발 가이드가 없다면 어떨까요? 일회성으로 API를 한번 호출하고 끝나면 편하겠지만, 많은 경우에 특정 API를 호출하기 전에 인증 API 등의 선제적 API를 호출해야 한다거나, 관리자 사이트 등에서 인증키 정보 등을 획득해야 할 경우, 이런 일련의 시작하기(Getting Started) 과정이 필요합니다. 하지만, API 문서에서 시작하기 내용이 누락된 경우가 실제로 많이 존재하는데요. 고객사에서 API 문서를 요청했을 때 Swagger 등의 링크나 API 명세서만 제시하는 경우가 대표적입니다. Swagger는 훌륭한 API 도구이지만, 사용 순서를 문서화 할 수 있는 공간에 제약이 있기 때문에 Swagger 링크와는 별개로 별도의 문서에 API의 사용 순서를 설명하는 시작 가이드를 제작하는 것이 바람직합니다.
• 사전 작업
API 사용에 앞서 보통 계정을 등록하거나 또는 API Key 등록과 인증하는 등의 사전 작업이 필요할 수 있습니다. 예를 들어 카카오워크 Web API를 이용하여 Bot을 생성할 때, 자동으로 부여받은 인증키(App Key)를 통해 어떤 Bot에서 받은 요청인지 인증 및 권한을 검사하는 작업이 필요합니다. 따라서 시작 가이드에는 사전에 인증키(App key)를 어떻게 발급할 수 있고 어떤 용도로 사용되는지 상세히 설명되어야 합니다.
[그림 1] API를 사용 전 인증 작업• API 사용 시퀀스
API에도 사용 시퀀스가 존재할 수 있습니다. 예를 들어 카카오워크 Bot을 생성한다고 했을 때, 위의 사전 작업 이후에 특정 멤버를 조회하고, 해당 멤버와의 채팅방을 생성하고, 메시지를 전송하는 일련의 시퀀스가 존재하는데요. 이런 사용 시퀀스가 없다면 외부 개발자들은 스스로 탐구하는 자세로 여러 API를 순서에 맞지 않게 호출해서 원하는 결과를 얻지 못할 수도 있습니다. 따라서 API 사용 시퀀스가 존재한다면 넘버링 형식으로 시퀀스를 정리하는 것이 좋습니다.
# API 레퍼런스
앞서 ‘API는 특정 기술을 사용하기 위한 약속이다’ 라고 했는데요. 이 약속들은 보통 요청 방식, 요청 파라미터 유형, 파라미터의 필수 여부 등을 의미합니다. 개발자는 이 약속들을 확인하고 용도에 맞게 코드를 작성해야 합니다. 앞서 이야기한 카카오워크 Bot에서는 멤버 조회, 채팅방 생성, 메시지 전송 등의 API를 사용해야 하는데요. 이런 API 별 요청과 응답을 정리해 놓은 문서가 바로 API 레퍼런스인데요. API 레퍼런스는 대게 요청(Request)와 응답(Response)로 구성됩니다.
• 요청 (Request)
먼저 API 요청을 제대로 하기 위해서는 특정 항목들을 일정 포맷에 따라 호출해야 하는데요. API 요청을 문서로 정리할 때 저희는 Request Syntax, Request Header, Request Element로 구분하고, 모든 서비스에 이 구성을 적용하고 있습니다.
[그림 2] 성공적인 API 요청① Request Syntax
Request Syntax는 API의 형태, 구조에 대한 정의를 나타냅니다. API가 어떤 메서드를 사용하고, 요청 URL의 형태는 무엇인지, 그리고 코드 예제가 함께 제공되어야 합니다.
[그림 3] Request Syntax 예시② Request Header
Request Header는 요청에 대한 추가 정보를 담고 있는 부분입니다. 예를 들어 메시지의 총 길이(Content-Length), 형식(Content-Type) 등이 Header에 포함될 수 있는데요. 앞에서 발급받은 인증을 위한 정보를 Header에 작성하기도 합니다.
Header 설명 Host 요청이 전송되는 URL User-Agent 요청을 보내는 클라이언트에 대한 정보 ex) 웹브라우저 정보 Content-Type 요청이 보내는 메시지 타입 ex) application/json Content-Length 요청하는 메시지의 길이
③ Request Element
Request Element는 해당 요청의 실제 메시지/내용이 해당됩니다. Request Element에는 API를 요청하기 위한 파라미터와 파라미터의 유형, 필수 여부와 설명, 제약 사항 등이 제공되어야 합니다. 간혹 Element가 없는 요청도 있는데요. 대표적으로 정보를 불러올 때 사용하는 GET 메서드에서 Element가 없는 요청이 나타나기도 합니다.
• 응답 (Response)
응답은 API 요청에 대한 결과값을 의미합니다. 예를 들어 특정 채팅방에 메시지를 전송했을 때 메시지가 정상적으로 전송되었는지 전송 결과를 확인할 수 있습니다.
① Response Element
Response Element에서는 API 요청에 대한 결과값을 확인할 수 있습니다. 요청한 API의 메서드에 따라 응답 형태는 달라질 수 있는데요. POST와 같이 값을 Body에 실어보낼 때는 해당 값이 잘 저장되었는지, 전달되었는지를 나타내는 성공여부를 나타내기도 하고, GET과 같이 특정 정보를 조회하거나 받아올 때는 값들을 코드로 확인할 수 있거나 자동적으로 다운로드 되기도 합니다.
Response Element에는 필드, 필드 유형, 필수 여부와 설명이 제공되어야 합니다. 만약 개발자가 특정 고객 정보에서 이름과 고객의 메일 주소를 가져오고 싶은 경우라면, 이름과 메일 주소의 필드 이름이 각각 무엇인지 알아야겠죠?
︱ 좋은 API 문서 작성 Tips
앞서 나온 API 문서 구성 요소들을 바탕으로 독자에게 더 친숙한 API 문서를 작성하는 방법은 무엇일까요? 저희 테크니컬라이팅 팀에서는 여러 자료를 비교 분석하여 API 문서 작성에 대해 스터디하고 있는데요. API 문서화와 관련된 몇 가지 Tip을 공유해 드리겠습니다.
# API 리스트업
여러분은 ‘카카오워크 Bot’ 하면 어떤 기능이 떠오르시나요? Bot을 이용해 회원들에게 메시지를 보낼 수도 있고, Bot이 회원들의 정보를 가져올 수도 있고, 특정 워크스페이스에 정보를 조회할 수도 있겠죠? 카카오워크 Web API 레퍼런스에 담긴 API만 해도 18개인데요. 이처럼 하나의 API 레퍼런스 안에는 다양한 API가 제공됩니다. 사실 개발자는 모든 API를 다 사용하기보다는 개발하고자 하는 기능에 맞는 API를 선택해서 사용합니다. 이때 API를 종류에 따라 구분하고 한눈에 리스트업한 후 링크를 활용해 바로가기를 하면 API 사용에 용이합니다.
[그림 4] API 리스트업# 시각적 UI 활용
API 문서를 몇 번 읽어보신 분들은 아시겠지만 API문서는 파라미터 설명, 예제 코드, API 설명이 반복되는 글입니다. 이러한 글은 자칫하면 반복적인 나열 등 텍스트로만 작성되어 독자들을 지루하게 하는데요. 따라서 테이블 계층화나 코드 블럭 등 시각적인 요소들을 활용해 직관적으로 글을 작성하는 것이 필요합니다.
• 테이블 계층화
요청 또는 응답에서 사용되는 파라미터는 파라미터의 이름, 타입, 필수여부, 설명을 담고 있습니다. 이를 한줄씩 나열하면 파라미터가 줄글로 길어지기 마련인데요. 따라서 구분을 쉽게하기 위해 테이블로 작성하고 테이블을 계층화하는 것은 어떨까요? 응답 파라미터 요소 중에 파라미터 값 아래에 세부 파라미터들이 생기는 경우가 있는데, 이때 계층화를 이용하면 전체적인 API의 구성을 직관적으로 확인할 수 있습니다.
[그림 5] 테이블 계층화 예시• 코드블럭 활용
API를 사용할 때 파라미터의 이름이나 필수적으로 작성해야하는 값 등 고정된 값들은 그대로 작성되어야 하는데요. 따라서 고정된 값들을 작성할 경우, 코드 블록을 적용한다면 어떨까요? 독자들은 ‘이 값은 그대로 입력해야 하는 고정값’이라는 개념을 보다 쉽게 이해할 수 있게 될 것 입니다. 그리고 독자에게 일관된 메시지를 전달하기 위해, 이런 규칙은 모든 API에 일괄적으로 적용하는 것이 좋습니다. 또한 에러 코드 등 강조가 필요한 경우에도 코드 블록을 사용하면 좋은데요. 저희는 고정 입력값과 에러 코드에 코드블록을 적용하고 있는데요. 회사별 스타일 가이드에 따라 코드 블록을 적용할 항목들을 정했다면, 이를 일괄적으로 문서에 반영하는 것이 좋겠죠?
# 지속적인 업데이트
API 레퍼런스를 게시했다고 해서 API 문서 작업이 끝난 것은 아닙니다. API는 기술의 변화와 사용자의 피드백을 반영하여 지속적으로 업데이트되고 있는데요. API는 업데이트되었는데, 레퍼런스가 그대로일 경우 문서는 뒤떨어진(out of date) 문서가 됩니다. 사용자 입장에서는 문서의 지시를 분명히 따랐음에도 불구하고 API를 원하는 대로 사용할 수 없거나 잘못된 결과가 나올 수 있으니 지속적인 업데이트가 필요합니다.
마치며
지금까지 API 레퍼런스 구성부터 API 문서 작성 Tip까지 살펴보았는데 어떠셨나요?
API 문서는 개발자가 API를 사용하기 위한 모든 것을 담고 있는 문서인데요. 개발자 입장에서는 부정확하고 신뢰성 떨어지는 문서로 인하여 시간을 낭비하는 일이 발생해서는 안될 것 입니다. 이번 포스팅에서 API 문서화의 구성과 작성 방향을 이해하는데 도움 되셨길 바라며, 저희의 다음 톺아보기 시리즈도 기대해 주세요. 감사합니다 🙂
📍 테크니컬 라이팅 관련 글 더보기
✓ 퇴고의 기술
✓ 올바른 동사 사용 가이드
✓ 기술문서의 쉼표 사용 가이드라인
✓ Release Note 톺아보기
✓ 개요 작성의 중요성
✓ 개발자들을 위한 테크니컬 라이팅 10계명
✓ 목차의 중요성
✓ 기술 문서 작성 5단계
✓ 테크니컬 라이팅 4대 원칙
✓ 기술 문서 쉽게 쓰기 지침
✓ 언어학 관점에서의 기술문서 가독성 향상 전략
✓ 카카오 i 기술문서 사이트 여정, 그리고 벌써 한 달
✓ Technical Writer에서 Technical Communicator로…
✓ [KREW INSIDE] AI 서비스의 기술 문서를 책임지는 사람들, 테크니컬 라이터
Crystal (김유리) 사용자의 입장에서 생각하고, 개발자와 원활한 소통을 할 수 있는 Communication Skill을 가진 Technical Communicator입니다. 카카오엔터프라이즈의 값진 기술들을 정확하고 명확하게 전달하고, 신뢰를 쌓을 수 있는 문서를 만들고자 합니다.
Sandy (차신영) 산더미처럼 쌓여진 문서 정리, 새로운 문서화 도구 테스트, 그리고 구글링이 취미인 Technical Communicator입니다.
July (김정인) 새로운 것에 관심갖고, 뛰어드는 것이 즐거운 Technical Communicator 인턴입니다.
문서 엔지니어링과 API 문서화
이 글은 마이크로소프트웨어 396호에 기고된 글입니다.
들어가기
테크니컬 라이터(technical writer)라는 말을 들으면 대부분 ‘라이터’라는 단어만 보고 ‘글 쓰는 사람’이라 생각하기 십상입니다. 물론 틀린 것은 아니지만, 실상 키보드를 두드리며 글 쓰는 일이 테크니컬 라이터 업무의 대부분을 차지하지는 않습니다. 하루에 얼마 동안 글을 쓰는지 측정해 본 적은 없으나, 테크니컬 라이터 톰 존슨(Tom Johnson)이 말하기로는 일하는 시간의 약 10%라고 합니다.
그렇다면 그 밖의 시간에는 뭘 할까요? 역시 톰 존슨에 따르면 개발자 인터뷰, 다른 사람이 쓴 문서 리뷰, 앱 스크린 캐스팅이 필요할 때 아이폰 탈옥, 미디어위키에서 링크된 이미지에 캡션 넣는 방법 찾기 등등이라고 합니다. 그중에서도 제가 말하고자 하는 일은 비록 ‘아이폰 탈옥’ 같은 건 아니지만 결과적으로는 글쓰기와는 전혀 관계 없어 보이는 엔지니어링에 관한 것입니다.
기술 문서 작업을 해보면 한 번 이상은 이런 요청을 받게 됩니다.
‘기술 정보를 담은 텍스트 파일 200개를 워드 파일 하나로 만들어 주세요.’
‘사내 위키에 쓴 게시물을 공식 개발자 사이트에 올려주세요.’
이런 요청을 받았을 때 취할 수 있는 방법은 단 하나, ‘복붙(복사해서 붙여넣기)’입니다. 물론 고결한 지성을 발휘해 텅 빈 백지에 새로운 글 한 편을 써내야만 하는 테크니컬 라이터에게 있어, 아무런 지성을 동원하지 않아도 되는 이런 작업은 재충전 기회기도 하니 하루 정도 투자할 가치는 있습니다. 그런데, 일주일 후 또 이런 요청이 들어옵니다.
‘텍스트 파일을 살펴봤더니, 구버전에만 적용되는 내용이 있었어요. 200개 파일에서 군데군데 수정했으니, 그 부분만 지난번에 만든 워드 파일에 업데이트해주세요.’
그들은 ‘그 부분만 업데이트’라고 말하지만, 부분 업데이트는 자칫하면 빠뜨리는 곳이 생기거나 다른 부분을 망가뜨릴 수 있어서 결국엔 전체를 다시 한번 손봐야 하는 일입니다. 저와 제 동료는 이를 ‘인형 눈알 꿰기’라고 불렀습니다. 애초에 워드 파일에 업데이트해주면 좋으련만, 그렇게는 안 됩니다. 왜 안 되는지는 블로그 분량의 한계 때문에 구구절절 말할 수 없으나, 보통 그렇고 그런 이유로 인형 눈알 꿰기 작업이 반복적으로 발생합니다.
몇 번쯤 인형 눈알 꿰기를 하던 열정에 찬 신입 테크니컬 라이터는 자연스럽게, 워드 파일을 만든 Microsoft를 원망하게 됩니다. 그리고 분노와 원망의 단계를 넘어서고 난 뒤 비로소 문서 엔지니어로 거듭납니다. 테크니컬 라이팅과 문서 엔지니어링이 떼려야 뗄 수 없는 관계인 이유입니다.
저는 본래부터 도구를 만들고 쓰는 것을 좋아해서, Microsoft를 원망하는 기간이 조금 짧았습니다. 덕분에 좀 더 빨리 문서 엔지니어의 길로 들어섰고, 이렇게 그에 관한 글을 쓰고 있습니다. 생각해보면 테크니컬 라이터가 된 후, 처음 맡은 프로젝트에서 백여 개 엑셀 파일을 워드 파일 하나로 만드는 작업을 하게 된 것이 그 길의 시작이었습니다. 당시 프로젝트 매니저 역시 반복되는 엑셀-워드 간 복붙이 비효율적이라고 느껴 해결책을 찾던 중이었습니다. 저는 그 일을 맡아 오피스 오픈 XML(Office Open XML)을 이용해 엑셀을 워드로 변환하는 도구를 만들었습니다.
처음에는 엑셀을 워드로 바로 변환했지만, 데이터 버전 관리와 양방향 변환이 필요해져 엑셀 데이터를 표준 XML 형태로 변환, 저장한 다음 워드 파일로 출력하게 바꿨습니다. 배운 게 도둑질이라고 그 후 저는 문서 생성 자동화, 다양한 포맷 지원을 위한 문서 표준화에 관심을 가지게 됐습니다.
문서 엔지니어링에 속하는 작업은 다양합니다. 문서화 프로세스를 구축하고 프로젝트 산출물을 관리하는 것도 문서 엔지니어링이지만, 이 글에서는 제 관심 분야인 문서 변환과 자동화에 관해서만 써보려고 합니다.
API 문서화
테크니컬 라이팅 업무 가운데 API 문서화는 문서 엔지니어링이 가장 많이 적용되는 분야입니다. 이 글에서 다른 기술문서가 아닌 API 관련 문서를 다루는 것도 그런 이유입니다.
API 문서, 주로 API 레퍼런스라고 부르는 이 기술 문서는 프로그래밍 역사와 함께 존재해왔습니다. 뜻 맞는 친구 몇 명이 모여 소프트웨어를 만들던 시절에 반드시 테크니컬 라이터가 함께 했다곤 할 수 없을 테니, 대부분은 프로그래머가 직접 API 레퍼런스를 썼을 것입니다. 처음에는 텍스트 파일로 썼겠지만, 소스코드와 동기화하기도 어렵고 문서를 별도로 작성해야 하므로 부담스러웠겠지요. 그 덕분에 소스코드에서 API 레퍼런스 작성하는 방법이 생겨난 것으로 추측할 수 있습니다.
API 레퍼런스는 흔히 개발 문서라고 하는 개발자 가이드와는 약간 다릅니다. 개발자 가이드는 내용 흐름과 연관 관계가 있지만, API 레퍼런스는 API 간 순서나 연결이 거의 없습니다. 극단적으로 말하면, 한 API 설명이 곧 하나의 문서인 셈입니다. <그림 1>과 <그림 2>에서 보는 것처럼 개발자 가이드는 설명글이 길게 이어지지만, API 레퍼런스는 유사한 것끼리 분류는 했으나 각자 역할만 설명하고 있습니다.
<그림 1> LINE 개발자 가이드 예(LINE SDK for iOS)
<그림 2> LINE API 레퍼런스 예(LineSDKJSONWebToken)
API 레퍼런스는 각 API 설명 형태도 무척 비슷합니다. 라이브러리 API나 프레임워크 API는 함수(메서드)명, 설명, 파라미터, 반환 값이 반복되고, REST API는 엔드포인트(endpoint), 설명, 파라미터, 응답 설명이 반복됩니다. 이처럼 서로 연결되지 않으며 반복되는 구조를 가진 문서는 도구를 이용해 작업하기 좋습니다. 그래서 개발자 가이드를 자동으로 만들어주는 도구는 없어도, API 레퍼런스를 만들어주는 도구는 예전에도 있었고 지금도 계속 발전하고 있습니다.
1995년, 썬 마이크로시스템즈(Sun Microsystems)가 자바(Java)와 함께 소스코드 주석을 이용해 API 문서를 만드는 자바독(Javadoc)을 선보였고, 20년이 지난 지금까지도 널리 쓰이고 있습니다. 자바독의 성공에 고무된 덕분일까요. 다른 프로그래밍 언어도 소스코드를 이용한 자체 문서화 도구를 속속 내놓았습니다. 소스코드 기반은 아니지만, REST API를 위한 ‘OpenAPI Specification(이하 OAS)’도 문서화 도구를 제공합니다.
API 레퍼런스는 꼭 필요할까
이 분야에서 수년간 일한 경험에 기반하여 기술 문서 중에서 개발자가 가장 많이 보는 것은 API 레퍼런스라고 어렴풋이 느끼고는 있었지만, 주관적인 느낌일 뿐 뒷받침해 줄 데이터가 없었습니다. 그런데 고맙게도, SIGDOC에서 실험을 통해 정량적인 데이터를 발표했습니다. 모집단이 작긴 하지만 이런 유의 조사가 많지 않으니 개발자가 새로운 API를 마주했을 때 어떤 행동을 하는지 참고할 만합니다.
SIGDOC가 발표한 데이터를 참고해 만든 <그림 3>은 개발자가 처음 접하는 API를 사용해 문제를 해결할 때 어떤 부분에 얼마나 시간을 할애하는지 보여줍니다.
<그림 3> 문제 해결 시간 동안 개발자 시선이 머문 곳(How Developers Use API Documentation: An Observation Study, SIGDOC)
가장 많은 부분을 차지한 ‘Editor & Client’는 문서 외 작업 시간입니다. 이를 제외하면, 개발자가 기술 문서를 볼 때 가장 많은 시간을 할애한 부분이 API 레퍼런스임을 확인할 수 있습니다. 따라서 인력 및 시간 부족으로 모든 문서를 작성하기 어려운 프로젝트라도 최소한 API 레퍼런스는 작성하는 것이 좋습니다. 그래야 누군가 사용해줄 테니까요. 운 좋게도 API 레퍼런스는 개발자가 작성하기에 가장 부담 없는 문서입니다. 구구절절 이야기를 나열할 필요도 없고, 딱 정해진 내용만 쓰면 되기 때문입니다.
API 레퍼런스에는 무엇을 써야 할까
API 문서화 요청을 받으면, 저는 보통 다음 순서로 작업합니다.
API 유형 및 프로그래밍 언어, 출력 포맷을 확인한다. 그에 맞는 도구를 선정한다. API 하나를 골라 설명 샘플을 작성한다. 어디에 뭘 작성해야 하는지를 설명하는 가이드 템플릿을 작성한다. 개발자에게 API 설명 작성을 요청한 후, 그 내용을 검토한다. 전체 프로세스를 검수한 다음, 문서 생성을 자동화한다.
5, 6번 단계까지 진행할 수 있다면 더할 나위 없는 문서가 될 수 있습니다. 하지만 프로젝트 종료까지 테크니컬 라이팅을 전담해주지 못한다면 4번 단계까지만 작업해도 꽤 만족스러운 결과를 얻을 수 있습니다.
1번 작업이 필요한 이유는 API 유형과 프로그래밍 언어, 출력물 포맷에 따라 사용할 도구와 가이드 템플릿이 달라지기 때문입니다. 예를 들어, Android용 라이브러리 API 레퍼런스를 HTML으로 만들려면 자바독을 사용하고, 스프링(Spring)으로 작성한 REST API 레퍼런스를 웹서버로 공개하려면 스웨거(Swagger)를 사용하고, 파이썬(Python)으로 작성한 라이브러리의 API 레퍼런스를 전자책으로 배포하려면 스핑스(Sphinx)를 사용하는 식입니다.
아래 코드는 소스코드 주석 기반 API 레퍼런스 생성 도구인 자바독의 예시입니다.
/** * 내가 만든 정말 멋진 클래스 * @author jeongeun.jeon * @version 0.1 */ public class MyFantasticClass { /** * 주어진 값의 2배를 계산한다. * * 정수가 아닌 값의 두 배를 얻으려면 see also에 있는 항목을 참고하라. * * @param base 두 배 하고자 하는 값. 0부터 100까지만 입력할 수 있다. * @return 주어진 값의 두 배 * @see getDouble(float) */ public int getDouble (int base) { …(중략) } }
보통은 IDE(integrated development environment)가 메서드 프로토타입에 따라 자동으로 필요한 태그( @param , @return 등)를 입력해줍니다. 이 태그를 보면 작성해야 할 내용이 무엇인지 알 수 있습니다. 이처럼 정해진 형식에 맞춰 내용을 작성하게 하는 것은 API 레퍼런스 도구의 기본 기능이자 쓰는 사람이 포기하지 않도록 붙잡아주는 끈입니다. 테크니컬 라이터도 백지를 펼쳐놓고 글을 쓰라고 하면 아득해지는데, 하물며 개발자에게 텅 빈 텍스트 파일을 주면서 쓰라고 하면 어떻게 될까요? 물론 잘 쓰는 사람도 있지만, 보통은 첫 문장을 시작할 때까지 시간이 한참 걸릴 것입니다. 정해진 형식에 따라 내용을 채우게 하는 방법은 객관식 문제와 유사해서, 설명글을 작성하는 속도가 훨씬 빨라집니다.
이 방법이 써야 할 항목을 정해주고 뭘 써야 할지 알려주긴 하지만, 각 항목에 꼭 필요한 내용을 쓰게 하려면 이것만으로는 부족합니다. 4번 단계처럼, 이 부분에는 어떤 내용을 쓰고 어떤 내용을 쓰지 말아야 하는지 설명해주는 가이드 템플릿을 함께 제공하는 것이 좋습니다. 가이드 템플릿은 프로그래밍 언어 또는 API 유형에 따라 다릅니다.
아래 코드는 자바독 가이드 템플릿입니다. 파라미터 설명 가이드 등은 유사한 구조를 가진 다른 API에도 적용할 수 있습니다.
/** * 첫 문장에는 동사를 사용해 메서드의 역할을 설명하십시오. ‘무엇을 반환한다’는 지양하십시오.
* 줄바꿈한 다음 아래와 같은 정보가 있으면 기술하십시오. * – 이 메서드를 호출하기 전후에 해야 하는 작업이 있다면 기술하십시오. * – 특정한 상황에서 이 메서드를 사용하지 말아야 한다면 이유를 설명하십시오. * *참고* 영어로 쓴다면 첫 글자는 대문자로 쓰십시오. * * @param base 어떤 의미의 파라미터인지 쓰십시오. * boolean 값이라면 언제 true이고 언제 false 인지 쓰십시오. * 숫자라면 범위가 있는지 쓰십시오. enum이라면 그 enum 항목을 링크하십시오. * 허락되지 않은 값을 전달했을 때 무슨 일이 발생하는지 쓰십시오. * @return 무엇을 반환하는지 명사로 쓰십시오. * boolean 값이라면 언제 true이고 언제 false 인지 쓰십시오. * 숫자라면 범위가 있는지 쓰십시오. enum이라면 그 enum 항목을 링크하십시오. * 문제가 발생했을 때 일반 상황과 다른 의미의 값을 반환한다면 기술하십시오. * (예: -1을 반환하는 경우) * @see 유사한 기능을 하는 메서드가 있다면 기술하십시오. * 어떤 스펙을 구현한 것이라면 그 스펙의 이름 혹은 링크를 기술하십시오. */ public int getDouble (int base) { …(중략) } }가이드 템플릿에도 나와 있지만, API 설명에서 가장 자주 빠뜨리는 내용은 바로 파라미터나 반환 값의 범위입니다. 반환 값이 나열형이라면 어떤 값을 쓸 수 있는지 나열해야 하고, 반환 값이 숫자라면 그 범위나 값의 의미를 함께 설명해야 합니다. 이를 빠뜨리면 API 레퍼런스를 보고 개발하는 사람이 시행착오를 겪기 때문입니다.
따라서, 이런 주의사항을 쓴 가이드 템플릿을 제공하면 훨씬 빠르고 정확하게 설명문을 작성할 수 있습니다. 이렇게 작성된 내용으로 <그림 4>와 같은 출력물을 만들면 API 레퍼런스 작성이 끝납니다.
<그림 4> 자바독 출력물 예(LINE SDK v5.0.0 for Android)
가이드 템플릿이 없더라도 도구를 이용해서 이런 상황을 막을 수 있을까요? 소스코드 주석 기반 도구에서 좀 더 발전한 것이 API 명세서 기반 도구입니다. 이 중 OAS가 그런 기능을 제공합니다. OAS의 주목적은 문서화가 아니라 설계 및 테스트이므로, API를 정의할 때 API가 사용할 객체를 명확히 입력하도록 권장합니다. 예를 들어, 객체의 필드가 enum 이면 enum 스키마를 정의한 후 그 위치로 레퍼런스하고, 객체의 필드가 숫자면 최댓값과 최솟값을 입력해 범위를 지정합니다. 비록 필수는 아니지만 다른 도구에 비해 범위 지정을 빠뜨리는 횟수를 줄일 수 있습니다.
API 레퍼런스는 어떻게 게시할까
API 레퍼런스 생성 도구 대부분은 HTML 출력물을 만드는 기능이 있습니다. 오픈소스 프로젝트, 특히 전담 테크니컬 라이터가 없는 프로젝트는 이런 도구를 이용해 만든 HTML 파일을 깃허브 페이지(GitHub Pages) 등에 업로드하면 충분합니다. 하지만 공식 개발자 지원 웹사이트를 가진 회사라면 상황이 조금 다릅니다. CMS(content management system) 같은 웹 콘텐츠 관리 도구로 공식 웹사이트를 만들거나 README.io, Apiary 같은 개발 문서 서비스를 사용하는 곳도 있습니다. 물론 자체 제작한 웹사이트를 사용하는 곳도 있습니다. 어느 쪽이든 <그림4>에서 본 출력물을 그대로 게시하기에는 어려움이 따릅니다. 기술적인 어려움도 있지만 정책적인 어려움도 있습니다.
구글만 해도, Android API 레퍼런스를 자바독 기반 독릿(doclet)인 Doclava를 사용해 서비스했으나, 자체 도구로 바꾼 지 오래입니다. 소스코드 주석에 기술한 API 설명을 보면 자체 도구도 자바독 기반일 것으로 짐작됩니다.
<그림 5> Android API 레퍼런스 화면
Microsoft는 어떨까요? Microsoft는 IT 기업 가운데 기술 문서를 오픈소스화한 대표적인 곳입니다. 깃허브에 있는 애저(Azure) 기술 문서를 잘 들여다보면, REST API를 자체 정의한 YAML 형식1으로 기술한 것을 볼 수 있습니다. 애저 공식 웹사이트는 이 데이터 정보를 API 레퍼런스로 만들어 제공합니다.
<그림 6> 애저 API 레퍼런스 화면
애저 문서 저장소에서 찾아본 YAML 데이터는 아래 코드와 같습니다.
– uid: azure-arm-sql.JobVersions.get name: ‘get(string, string, string, string, number, Object)’ children: [] type: method langs: – typeScript summary: Gets a job version. syntax: content: >- function get(resourceGroupName: string, serverName: string, jobAgentName: string, jobName: string, jobVersion: number, options?: Object) parameters: – id: resourceGroupName type: – string description: > The name of the resource group that contains the resource. You can obtain this value from the Azure Resource Manager API or the portal. …(중략)
오픈소스 프로젝트인 Enact 역시 개발 문서를 깃허브에 공개했으므로, 어떤 도구를 사용했는지 추측해볼 수 있습니다. Enact의 자바스크립트 API 레퍼런스는 JSDoc 형식으로 소스코드에 기술하고, 자체 엔지니어링을 거쳐 웹사이트에 게시하는 방식입니다.
<그림 7> Enact API 레퍼런스 화면
Android와 Enact는 소스코드 주석을 사용하고, 애저는 YAML 기술 형식을 사용했습니다. 방식이 다른 이유는 사용하는 프로그래밍 언어와 API 유형에 따라 널리 사용되는 도구를 활용했기 때문일 것입니다. 그렇다 해도 이 도구를 회사 공식 웹사이트에 통합 적용하기 어려웠다면 과연 사용했을까요?
자바독과 JSDoc은 출력물 커스터마이즈를 지원하며, 애저는 OAS와 유사한 자체 API 명세서를 사용했으므로, 기존 웹사이트에 어울리도록 출력물을 바꿀 수 있습니다. 즉, 세 예시 모두 공식 웹사이트에 잘 녹아드는 출력물을 만들 수 있는 도구 혹은 방법을 선택한 것입니다.
데이터 기반으로 말해야 하는 공학도로서 다소 어울리지 않는 말이지만, 솔직히 말해 외부에 공개하는 문서는 겉모습도 중요합니다. 겉보기에 깔끔하고 아름다운 문서는 글을 읽기 전부터 독자의 관심과 신뢰를 얻을 수 있기 때문입니다. 물론 내용도 제대로 돼 있어야 하지만, 애초에 겉모습이 기업 이미지에 맞지 않거나 아마추어 같으면 내용을 읽기도 전에 신뢰도가 하락할 것입니다.
이런 이유로 저는 외부 공개 문서를 작성할 때 자바독이나 독시젠(Doxygen), 스웨거 등이 제공하는 기본 출력물 사용을 권장하지 않습니다. 기본 출력물은 회사 브랜드 아이덴티티를 담기 어렵고, 그간 회사가 쌓아 온 신뢰감을 문서에까지 전달해주지 못하기 때문입니다. 개인적으로는, 몸담은 회사가 문서 엔지니어링에 대한 기술이나 관심이 없는 것으로 오해를 받을까 우려되기도 합니다.
API 레퍼런스는 이를 사용하는 개발자가 가장 많이 보는 기술 문서이며, 문서 엔지니어링을 어떻게 하느냐에 따라 작성 시간 및 출력물 모양이 크게 달라집니다. 이런 이유로 전문 테크니컬 라이팅 팀을 보유한 회사라면 자체 API 문서화 솔루션을 가져야 한다고 생각합니다. 완전히 새로운 도구를 만들어야 한다는 것이 아니라, 이미 있는 도구를 사용하더라도 트렌드 변화에 맞춰 정확하고 전문적인 결과물을 내놓는 프로세스를 가지고 있어야 한다는 뜻입니다. 구글도 그렇고 Microsoft도 그렇습니다. LINE 역시 다르지 않습니다.
좋은 API 레퍼런스 솔루션
그럼 좋은 API 레퍼런스 솔루션이란 어떤 것일까요? 앞서 언급한 예시에서 두 가지 조건을 찾아볼 수 있습니다.
출력 형식이 바뀌어도 쉽게 적응할 수 있어야 한다.
작성하는 사람이 뭘 써야 하는지 쉽게 알 수 있어야 한다.
Android 개발자 사이트는 여러 차례 리뉴얼됐으나, API 레퍼런스는 겉모양만 바뀌었을 뿐 소스코드에 자바독으로 설명을 작성하는 방식은 바뀌지 않았습니다. 소스코드에 작성한 내용을 웹페이지로 변환할 때 구글이 사용한 도구가 웹사이트의 변화에 쉽게 적응할 수 있다는 뜻입니다.
Android 예에서 보듯 API 레퍼런스가 공개될 웹사이트의 형태는 언제든지 바뀔 수 있습니다. 종종 웹사이트가 아닌 PDF 같은 파일이 최종 배포 형태가 되기도 합니다. ‘손목시계로도 인터넷이 되는 시대에 PDF라니’하고 어리둥절하는 사람도 있겠지만, 현장에서는 아직도 PDF가 많이 쓰입니다. 불특정 다수가 아닌 특정 그룹에만 배포하거나, 공식 웹사이트 공개 전에 배포하는 문서가 그 예입니다.
물론 나중에는 그 문서를 웹사이트에서 배포하게 될 가능성이 높습니다. 처음에는 문서를 PDF로 배포하다가 몇 달 뒤 웹사이트에 공개하는 문서화 프로젝트를 저도 몇 번 경험했습니다. 따라서 새로 시작하는 프로젝트에서 매니저가 API 레퍼런스는 PDF로 배포하겠다고 선언하더라도, 테크니컬 라이터는 웹 배포까지 염두에 두는 것이 좋습니다.
변화하는 출력물에 빠르게 대응하기 위해서는 데이터(설명)와 뷰(출력 형태)를 분리하는 것이 기본입니다. 데이터는 인라인 포매팅 외 출력물에 관한 어떤 정보도 포함하지 않아야 하며, 뷰는 데이터에 담긴 정보를 표출하되 형태를 쉽게 변경할 수 있어야 합니다. 이렇게 데이터를 분리해낸 후 어디에 무엇을 써야 하는지 명시적으로 나타내는 구조로 기술하면, 좋은 API 문서화 솔루션의 두 번째 조건을 달성할 수 있습니다.
자바독, JSDoc, OAS와 유사한 YAML 형식 모두 데이터와 뷰를 분리하고 명시적인 구조로 데이터를 작성하게 했습니다. 앞에서 본 예시처럼, 셋 모두 텍스트 기반으로 API 설명을 작성한 다음, 그 데이터에 원하는 뷰를 적용해 출력물을 생성합니다.
앞서 언급한 도구가 지원하지 않는 것, 예를 들어 C++로 작성한 API나 gRPC API는 레퍼런스 문서를 어떻게 만들어야 할까요? 솔직히 말하면, 둘 다 서드파티 API 레퍼런스 작성 도구가 있으니 큰 문제가 되지는 않습니다. 하지만 좀 더 나아가서, 하나의 프로젝트에서 다양한 프로그래밍 언어나 다양한 API 유형을 제공한다고 생각해봅시다. 프로그래밍 언어별로 각각 다른 도구를 사용한다면 프로젝트 전체 API 레퍼런스는 제각각 다른 형태가 될 수밖에 없습니다. 이것까지 고려한다면, 좋은 API 문서화 솔루션 조건을 하나 더 추가해야 합니다.
다양한 프로그래밍 언어와 API 유형을 통합할 수 있어야 한다.
API 레퍼런스 솔루션 유스케이스
좋은 API 문서화 솔루션을 위한 세 가지 조건을 달성하기 위해 <그림 8>과 같은 API 문서화 솔루션을 구상해보았습니다.
<그림 8> 좋은 API 레퍼런스 솔루션 조건을 달성하기 위한 API 문서화 작업 흐름
<그림 8>에서 보는 것처럼 소스코드 주석을 이용한 문서화 도구가 있다면 재활용하고, 그런 도구가 없으면 텍스트 기반으로 자체 기술 포맷을 만듭니다. 구조화 데이터용으로 쓰는 XML, JSON, YAML 등의 형식을 사용하는 게 좋겠습니다. 소스코드와 별도 포맷으로 작성한 데이터는 출력 형식을 정의한 템플릿을 적용해 최종 출력물로 변환됩니다. 사용하는 템플릿 언어는 각자 편리한 것을 선택합시다. 저는 이 솔루션을 ‘API 레퍼런스 템플릿’이라고 부르기로 했습니다.
제가 진행하는 프로젝트는 모두 API 레퍼런스 템플릿을 적용했습니다. 안타깝게도 아직 공개하지 않은 프로젝트이기에, 이 글에서는 가상의 데이터를 이용해 API 레퍼런스 템플릿이 무엇인지 소개하려 합니다. 가상 프로젝트는 C++ 기반의 라이브러리 API와 REST API를 제공합니다. 테크니컬 라이터 손에 들어왔을 때 라이브러리 API 설명은 소스코드 주석에, REST API 설명은 사내 협업 도구를 이용한 웹 게시물에 기술돼 있었습니다.
아래 코드는 가상 프로젝트의 C++ 라이브러리 API 설명입니다.
namespace mine { /** * 내가 만든 완벽한 C++ 클래스. * 생성 후에는 반드시 `CallMe()`를 호출해야 합니다. */ class MyClass { public: /** * 용건 있을 때 전화해달라는 함수. */ void CallMe(void); /** * 내 질문에 대답하게 하는 함수. * @question 내가 한 질문. null이면 반드시 false를 반환합니다. * @return 질문에 대한 응답. 응답이 ‘그렇다’면 true, ‘아니다’면 false를 반환합니다. */ bool AnswerMe(char *question); …(중략) }; }
<그림 9> 가상 프로젝트의 REST API 설명
제가 할 일은 두 종류 API 레퍼런스를 통합해 같은 형식으로 웹사이트에 게시하는 것입니다. 우선 현 상태를 분석해서 어떤 도구를 사용할지 생각해봅시다.
라이브러리 API는 소스코드에 설명을 작성했으니 데이터를 뷰에서 분리한 상태입니다. REST API는 사내 게시판에 썼으니 데이터와 뷰가 혼재돼 있습니다. 따라서, 먼저 라이브러리 API 레퍼런스 데이터를 출력할 뷰 템플릿을 만들고, 그 다음 REST API 문서에서 데이터를 추출한 다음 또 뷰 템플릿을 만들고, 마지막으로 두 종류 API의 뷰를 문서 하나로 통합해야 합니다.
<표 1> API 레퍼런스 템플릿을 적용할 가상 프로젝트 상태
항목 라이브러리 API REST API 원본 소스코드 주석 사내 게시판 데이터-뷰 분리 분리 미분리 적용 가능한 기존 도구 독시젠 사용 가능 없음
<표 1>에서 보는 것처럼, 언어 독립적 문서화 도구인 독시젠(doxygen)을 사용해서 C++ 소스코드에 작성한 주석으로 API 레퍼런스를 만들 수 있습니다. 독시젠으로 HTML 파일을 생성할 수도 있지만, 커스터마이징이 까다로운 데다 우리 목적이 개별 HTML이 아닌 통합 HTML을 제공하는 것이므로, 직접 HTML을 생성하는 대신 통합하기 좋은 포맷으로 만들 것입니다.
사내 게시물로 작성한 REST API 설명은 변경이 잦을 땐 업데이트가 무척 불편하므로, 과감하게 이 방식을 포기하고 수동으로 데이터를 추출해 YAML로 재작성할 것입니다. 반드시 사내 게시물로 공유해야 한다면, 이 YAML 파일을 공유할 수 있습니다. 그 후 각각 데이터를 하나의 문서로 만들려면 언급한 것처럼 HTML이 아닌 통합이 쉬운 포맷을 사용해야 합니다. 여기서는 그 중간 출력물 포맷으로 마크다운(markdown)을 선택했습니다.
C++ 라이브러리 API 레퍼런스 작업
우선 소스코드에 있는 라이브러리 API 주석을 마크다운으로 변환합시다. 독시젠은 마크다운 출력을 지원하지 않지만, 자체 정의한 XML 형식으로 API 명세서를 만들 수 있습니다. 이 명세서에는 소스코드가 빠진 순수 API 설명만 담깁니다.
<그림 10> 독시젠 실행 화면
<그림 10>처럼 독시젠의 옵션에서 XML을 출력하도록 설정하고 빌드합니다. 이렇게 생성한 XML 데이터를 다양한 출력물로 만들어주는 도구가 Moxygen입니다. 이를 이용해 마크다운으로 변환합니다.
아래 코드는 C++ 라이브러리 API 주석 데이터를 마크다운으로 변환한 결과(중간 출력물)입니다.
# class `mine::MyClass` {#classmine_1_1MyClass} 내가 만든 완벽한 C++ 클래스. 생성 후에는 반드시 [`CallMe()`](api-CallMe.md#classmine_1_1MyClass_1a20213a9d29c24324d6ea32a0010d3e9f)를 호출해야 합니다. ## Summary Members | Descriptions ——————————–|——————————————— `public void `[`CallMe`](#classMyClass_1adc72431f56d6803585f60cef6e467991)`(void)` | 용건 있을 때 전화해달라는 함수. `public bool `[`AnswerMe`](#classMyClass_1a98aecda3ae776dd1f99aad5f9990ff62)`(char * question)` | 내 질문에 대답하게 하는 함수. …(중략)
Moxygen도 뷰 템플릿을 커스터마이징할 수 있으므로, 필요에 따라 출력물을 수정할 수 있습니다. 하지만 가상 프로젝트에서는 기본 템플릿을 사용하고, 다음에 처리할 REST API 레퍼런스를 이와 비슷한 형태가 되도록 작성할 것입니다.
REST API 레퍼런스 작업
REST API 설명은 아래 코드처럼 YAML 포맷에 재작성합니다. 앞 예시에서 본 애저 기술 문서의 방법과 유사합니다.
summary: 사용자 정보 조회 path: /user/{user_id} method: GET description: |- 주어진 아이디(user_id)의 사용자 정보를 조회합니다. 요청이 성공적으로 서버에 전달되면 200 OK를 반환하며, 요청 처리 중 발생한 오류는 응답 객체의 `error` 필드에 나타납니다. parameters: – name: user_id in: path description: |- 조회할 사용자 ID. 사용자 ID는 [사용자 목록](/apis/user-list)에서 확인할 수 있습니다. required: true response: header: description: |- HTTP Result Code가 200 OK일 때 반환하는 정보입니다. [공용 응답 필드](/apis/response-common-fields)를 참고하십시오. body_segments: id: description: |- 파라미터로 수신한 `user_id` required: true type: string name: description: |- 사용자의 이름 required: true type: string image: description: |- 사용자의 사진이 저장된 URL required: false type: object …(중략)
척 봐도 OAS와 상당히 유사합니다. 다만, OAS는 모든 API를 한꺼번에 기술하고 응답 코드에 따라 좀 더 다양한 응답 설명이 있는데 반해, 여기서는 한 명세서에 한 API만 기술하고 응답도 ‘200 OK’로 한정했습니다.
물론, 각 프로젝트 특성에 따라 형식을 변경해도 상관없습니다. 이렇게 텍스트로 API 설명을 기술하면 소스코드와 함께 깃(Git) 저장소에서 버전을 관리할 수 있다는 장점이 있습니다. 또, API를 추가하거나 수정할 때도 이 형식에 맞춰 작성하게 되므로, 사내 게시물로 작성할 때보다 고정적인 데이터 구조를 유지할 수 있습니다. 즉, 누군가 정해진 형식에서 벗어나 임의로 테이블이나 그림을 입력할 수 없다는 말입니다.
이제 이 YAML 데이터를 마크다운으로 변환하는 작업이 필요합니다. 마크다운은 뷰를 포함한 문서이므로 레이아웃을 결정해야 합니다. 앞서 말한 대로 C++ 라이브러리 API 레퍼런스의 중간 출력물과 유사하게 만들 것입니다. 템플릿 언어는 핸들바(Handlebars)를 사용합니다.
아래 코드는 REST API의 YAML 데이터를 마크다운으로 변환할 템플릿입니다.
…(중략) ## Summary Members | Descriptions —————————|——————————————— {{#each paths}}{{toUpperCase method}} {{path}} | {{summary}} {{/each}} {{#each paths}} ## {{#if summary}}{{summary}}{{/if}} `{{toUpperCase method}} {{path}}` {{#if operationId}}{{addId operationId}}{{/if}} {{description}} {{! parameters }} ### Request parameters {{#if parameters}} Parameter | Type | Description :————–:|————-|—————————————— {{#each parameters}} `{{name}}`
({{in}}) | {{schema.type}} {{#if schema.items}} of {{schema.items.type}}{{/if}} | {{description}} {{#ifCond required “true”}}O{{/ifCond}} {{/each}} {{else}}None{{/if}} …(중략)YAML 파일을 읽고 이 템플릿 파일을 적용하면, 아래 코드와 같이 C++ 라이브러리 API 레퍼런스와 유사한 중간 출력물을 얻을 수 있습니다.
## Summary Members | Descriptions —————————|——————————————— GET /user/{user_id} | 사용자 정보 조회 ## 사용자 정보 조회 `GET /user/{user_id}` 주어진 아이디(user_id)의 사용자 정보를 조회합니다. 요청이 성공적으로 서버에 전달되면 200 OK를 반환하며, 요청 처리 중 발생한 오류는 응답 객체의 `error` 필드에 나타납니다. ### Request parameters Parameter | Type | Description :—————-:|————-|——————————————— `user_id`
(path) | | 조회할 사용자 ID. 사용자 ID는 [사용자 목록](/apis/user-list)에서 확인할 수 있습니다. …(중략)자체 API 템플릿을 구현하는 방법은 주제에서 벗어나기 때문에 상세히 설명하지 않고 깃허브 저장소의 설명과 코드로 대신합니다.
레퍼런스 통합
드디어 포맷은 같고 모양은 유사한 뷰로 두 종류의 API 레퍼런스를 출력해냈습니다. 이제 이들을 공식 웹사이트에 집어넣거나 지킬(Jekyll) 같은 정적 사이트 생성 도구를 이용해 자체 웹사이트를 서비스하면 됩니다. <그림 11> 화면은 포맷 변환 도구인 팬독(Pandoc)과 그 HTML 템플릿 중 하나를 이용해 통합 API 레퍼런스 웹페이지를 만들어본 것입니다.
<그림 11> 통합 API 레퍼런스 웹페이지
중간 출력물로 마크다운을 사용하면, HTML뿐 아니라 좀 더 다양한 파일 포맷으로 변환할 수 있습니다. <그림 12>는 그중 하나인 PDF 파일입니다.
<그림 12> 통합 API 레퍼런스 PDF
<그림 12>처럼 유려한 PDF를 만들려면 레이텍(LaTeX)을 사용해야 합니다. PDF 출력 방법에 관해서는 여기서 다루지 않으므로, 관심이 있으면 레이텍을 살펴보시기 바랍니다.
서로 다른 API 레퍼런스를 통합해야 할 필요가 없더라도, 다양한 파일 포맷을 지원하기 위해 마크다운을 중간 출력물로 사용하는 것도 좋은 방법입니다. 앞서 말한 것처럼 PDF 배포 후 웹사이트 게시로 진행되는 문서에 이 방법을 사용하면 웹사이트가 언제 공개돼도 즉시 대응할 수 있습니다.
끝맺기
API 레퍼런스를 작성할 때 중요한 요소를 소개하고, 이를 만족할 수 있는 API 레퍼런스 솔루션을 살펴보았습니다. 일견 복잡해 보일 수 있는 방법이지만, 이 모든 것을 스크립트를 통해 단번에 수행할 수 있습니다. 이렇게 프로세스화 된 문서 작업에서는 젠킨스(Jenkins) 같은 지속적 통합 도구를 이용하면 데이터(소스코드 혹은 YAML 파일) 변경 시 자동으로 최종 출력물을 만들 수 있으므로, 초기에 한 번 설정해 주면 손이 갈 일이 많지 않습니다.
독시젠 같이 널리 쓰이는 API 레퍼런스 생성 도구도 그 속을 뜯어보면 소스코드 주석에서 데이터를 추출하고 사용자가 변경할 수 있는 뷰에 데이터를 입혀 출력물을 커스터마이징 할 수 있게 해 놨습니다. 모든 작업이 가려져 있기에 복잡하게 보이지 않을 뿐, 결과적으로 이 글에서 소개한 방법과 크게 다르지 않습니다. 그래도 여전히 복잡해 보인다면, 프로젝트 특성에 따라 중간 출력물 생성 단계나 YAML API 명세서 작성 단계를 생략해도 좋습니다.
이 글의 목적은 쓸데없이 복잡한 프로세스를 적용하라고 권유하기 위함이 아닙니다. API 레퍼런스를 좀 더 쉽게 작성하고 관리하려면 이런 종류의 솔루션을 적용하면 좋겠다는 것이 말하고자 하는 핵심입니다.
이 글의 독자들은 앞으로 API 레퍼런스 생성 도구를 선정할 때 다음 두 가지를 꼭 고려하기 바랍니다.
데이터와 뷰를 분리했는가?
소스코드와 함께 버전 관리할 수 있는가?
첫 번째에 관해서는 본론에서 길게 설명했으니 더 말하지 않아도 될 것 같습니다. 두 번째는 이 글에 자세히 언급하지는 못했지만, 텍스트 기반 API 기술 방식을 적용하면 쉽게 달성할 수 있습니다.
이 글에서 소개한 API 레퍼런스 템플릿 중 YAML로 기술한 API 명세서는 두 가지 고려사항을 만족하는 도구 중 하나입니다. 소스코드 주석기반 문서화 도구가 없는 프로그래밍 언어를 사용하거나, 소스코드가 아직 없거나, 소스코드 수정을 극도로 꺼리는 프로젝트에 알맞은 방법입니다. 좀 더 전문화된 통합 API 레퍼런스 생성 도구가 발표되기 전까지, 앞서 언급한 문제로 인해 API 레퍼런스 작성에 애먹고 있는 사람들이 있다면 쓸만한 해결책이 될 것으로 믿습니다.
참고자료
개발자 로그: 변화를 위한 공간
API 문서는 개발자와 사용자가 원활하게 API를 파악하고 사용할 수 있도록 돕는 문서입니다. API 문서는 API의 기능을 분명하게 명시하고, 사용 방법과 관련 오류를 살펴볼 수 있게 해야 합니다.
일부 개발자들은 API 문서의 중요성을 간과하기도 합니다. 그러나 문서가 없다면 다른 사람들이 코드를 이해하는 데 많은 시간이 걸릴 것입니다. 개발자의 업무가 많은 경우에는 기술 문서를 작성하는 테크니컬 라이터가 이를 전문적으로 담당하기도 합니다.
오늘날 API 문서는 상품과 서비스의 일부로 간주되며 사용자 경험에도 중요한 영향을 미칩니다.
이번 글은
를 참고하였으며, API 문서를 작성하는 데 필요한 6가지 고려 사항을 담고 있습니다. 1. 개발을 시작하기 전에 문서를 작성하기
개발을 시작하기 전에 문서를 먼저 작성하는 것을 고려해보시기 바랍니다. 개발을 하지 않았는데 어떻게 문서를 작성할 수 있을까 싶지만, 해당 API가 어떤 기능을 할 것이며 이를 위해 사전에 필요한 사항들을 정리하는 것만으로도 유용합니다. 이를 통해 API 개발의 방향을 명확히 할 수 있으며, 문서 초안을 동료들에게 공유하고 피드백을 받을 수도 있습니다.
2. 두괄식으로 명시하기
API 문서의 첫 부분에는 해당 API가 정확히 어떤 작업을 위한 것인지 개괄적으로 명시해야 합니다. 이를 통해 문서에 접근한 이들은 해당 문서가 본인에게 필요한 것인지 판단할 수 있습니다.
또한 개발한 API 문서에는 아주 다양한 기능들이 포함되어 있을 것입니다. API 호출에 필요한 인증, 헤더 타입 등 이를 처음 보는 사용자가 어디서부터 어떻게 시작해야 하는지 기초적인 사항들을 도입부에서 설명하는 것이 좋습니다.
3. 문서를 읽는 대상자를 고려하기
API 문서를 읽는 대상은 크게 개발자와 사용자로 나눌 수 있습니다. 개발자와 사용자를 모두 고려하여 문서를 작성해야 합니다.
개발자들은 자신이 원하는 부분을 문서에서 빠르게 탐색하고 테스트하기를 원합니다. 이를 위해 일관적인 문서 구조와 예시를 제공할 필요가 있습니다. 세부 사항으로는 일관적인 헤딩 사용, 하이퍼링크 제공, 문단 나누기 및 리스트 활용을 고려할 수 있습니다.
사용자들의 수준은 초보에서 고급까지 다양할 수 있습니다. 초보 수준의 사용자를 염두에 두되 고급 사용자도 원하는 정보를 정확하게 얻을 수 있도록 해야 합니다. 즉, 필수적인 정보들을 정확하게 담되 가능한 쉬운 용어를 사용하는 것이 좋습니다. API 문서는 개발 지식이 없는 사람이 보더라도 이해할 수 있을 정도로 쉽고 간결하게 작성되어야 합니다.
4. 예시를 포함하기
대부분의 개발자들은 API 문서에서 안내하는 예시 코드를 복사 및 붙여넣기 하여 사용하기를 선호합니다. 이를 통해 테스트를 진행하고, 필요에 맞춰 수정해서 빠르게 사용할 수 있기 때문입니다. API의 핵심 엔드포인트를 테스트할 수 있는 예시를 제공하는 것이 좋습니다.
또한 응답 성공 예시와 에러 예시를 첨부해야 합니다 이 때 모든 에러가 아닌 가장 대표적인 에러들만 첨부하는 것이 좋습니다. 그렇지 않으면 문서가 너무 길어질 수 있습니다.
5. 좋은 API 문서 참고하기
이미 많은 기업들이 좋은 API 문서를 작성하여 제공하고 있습니다. 아래 사이트에 접속하여 좋은 API 문서로 언급되는 예시들을 참고해보실 수 있습니다.
6. 충분한 시간을 들이기
좋은 API 작성에는 시간이 필요합니다. API 문서는 개발자와 사용자를 위한 단순한 설명서가 아니라 상품의 일부이기도 합니다. API 작성을 위해 충분한 시간을 확보해야 합니다.
회사의 팀에서 일하고 있다면 다른 개발자 뿐만 아니라 기술 문서 작성자와 함께 문서에 대해 충분히 논의하는 것이 좋습니다. 만약, 팀 내부에서 문서를 이해하지 못하는 사람이 있다면 개선이 필요하다는 의미입니다.
API 문서는 한 번 작성하면 마무리 되는 작업이 아닙니다. 개발자와 사용자의 피드백을 반영하여 계속해서 문서를 업데이트해야 합니다
마치며
이상으로 좋은 API 문서 작성을 위한 사항들을 살펴봤습니다. 이를 정리하면 다음과 같습니다.
개발을 시작하기 전에 문서를 작성하기 두괄식으로 명시하기 문서를 읽는 대상을 고려하기 예시를 포함하기 좋은 API 문서 참고하기 충분한 시간을 들이기
반응형
api 문서화, 좋은 예시
0.
api 자급자족할 때는 딱히 신경쓰지 않았는데, 간만에 다른 사람이 쓸지도 모르는 상황이 돼서,
api 문서화를 찾아봤다.
1. swagger
이전 회사에서 쓰던 api 문서화 프레임워크.
베트남에 안드로이드/아이폰 어플 만드는 외주를 맡겼었는데 이 swagger가 정말 유용했다.
우리쪽에서 api를 만든 뒤, swagger를 업데이트해서 주면 따로 말로 설명할 필요가 없었다.
다만, 처음 사용이 좀 복잡하고…경우에 따라 작성/수정에 좀 오래 걸릴 수도 있다.
django에 swagger 관련 모듈이 있다!
근데 사용법을 잘 몰라서 몇 번 끼적여보다가 포기.
간지나던데…다음에 다시 도전!
2. Asciidoctor
Asciidoctor
문서 작성을 도와주는 툴인듯 하다.
자세히 읽어보진 않음
3. markdown
어떤 고마운 분이 깃허브에 markdown 언어로 api 문서화 형식을 올려주셨다.
이크 뭔가 gist로 가져오니 제대로 안 나온다…링크 타고 들어가서 보면 정말 간결하고 깔끔하다.
4. slate
와우!!!!!
내가 찾아헤매던 게 바로 이런 거였다!
깔끔하고 예쁘고 멋지다!!!
다만 윈도우는 지원하지 않는다 해서 ubuntu가 깔려있는 노트북으로 했다.
세팅도 굉장히 간단하고 무엇보다 예쁘다!
[Spring] API 문서작성 툴 고르기
서론
먼저 실제적인 개발전에 대략적인 준비를 마치고, 먼저 API를 설계해보기로 했다. 또한 설계뿐만 아니라, 프론트엔드 개발자에게 이 정보를 공유해야 하기 때문에 API를 문서화 하여 남겨 간편하게 내가 업데이트한 내용을 문서에서 확인 할 수 있도록 해보기로 했다.
어떤 툴을 사용할까
API를 문서화 하기 위한 여러 툴들이 있어서, 하나씩 알아보며 이번 프로젝트에는 어떤 툴이 적합할지 알아보았다.
Swagger
Swagger API 문서 예시 (링크)
Swagger는 무료로 제공되고, 문서자체에서 바로 해당 API를 테스트해 볼 수 있다는 점이 마음에 들었다. 그러나 API를 카테고리 별로 나누는 기능이 없어서 모든 API가 한페이지에 나타나기 때문에 후에 원하는 API를 한번에 찾을 수 없다는게 단점으로 느껴졌다.
Postman
Postman API 문서 예시 (링크)
Swagger보다 훨씬 문서의 느낌이 나고 UI가 깔끔해서 좋았다. 마크다운 형식으로 간단하게 문서를 작성 가능해서 Swagger보다는 훨씬 원하는 API를 찾기 쉬워서 좋아보였다.
게다가 실제로 날린 API 기반으로 자동으로 문서 부분을 생성해주고, 사용 예시까지 알려주기 때문에, 해당 API에 대한 코멘트만 추가해주면 알아서 자동으로 API 문서를 만들어주었다.
GitBook
GitBook API 문서 예시 (링크)
GitBook은 아주 깔끔한 UI가 장점이었다. Postman이나 Swagger처럼 웹에서 바로 해당 API를 테스트 해보는 기능은 없었지만, 해당 API를 굳이 날려보지 않아도 될 만큼 깔끔한 UI가 있어서 문서로써의 기능을 가장 잘하고 있는 것 같았다.
해당 API에 대한 파라미터와 응답까지 모두 기록하기 편하게 UI가 되어있어서 해당 API에 대한 세부사항 까지를 볼 수 있었다.
하지만 앞서 말했듯이 페이지에서 바로 해당 API에 요청을 날려볼 수는 없는 점이 너무 아쉬웠다.
결론
Swagger는 UI가 너무 맘에 안들기도 하고 직관적이지 않아서 문서의 느낌이 덜한 것 같아 Postman과 GitBook사이에서 고민했는데, Postman보다는 GitBook의 UI가 훨씬 직관적이고 디테일했지만, 온라인에서 바로 테스트 해볼 수 있는 기능이 없다는게 아쉬웠다.
하지만 자세하게 API 문서를 작성해놓으면 굳이 사용자가 해당 API를 테스트해 볼 필요가 있을까라는 생각이 들기도 했고, API 문서라는건 결국 문서이므로 직관적이고 깔끔하게 사용자가 보는것이 중요하다고 생각되서 GitBook으로 결정하기로 했다. Github와 연동이 가능하다는 점도 GitBook의 큰 장점으로 느껴졌다.
그럼 이제 작성 툴도 정했으니, API를 설계해서 문서의 초안을 대략 짜놓고 개발해가며 변경점을 적용해가며 문서와 함께 프로젝트를 시작해볼 것 이다.
API 문서 도구로 효율적인 문서 만들기
유연성과 확장성은 현대 시스템의 필수적인 부분이 되었으며 API(응용 프로그램 인터페이스) 는 이러한 기능을 제공하는 데 필수적인 역할을 합니다. 최신 웹 서비스를 제공하려면 효율적인 API를 구축하는 것이 중요합니다.
코딩과 개발은 모두 팀의 노력에 관한 것이기 때문에 신뢰할 수 있는 API 문서 도구를 사용하여 철저한 기록을 유지하고 API의 최대 효율성을 보장하는 것이 중요합니다. API 문서는 API의 성공 여부를 결정짓는 요소가 될 수도 있으므로 모든 API 서비스의 중요한 부분입니다.
API 문서 도구로 효율적인 문서를 만드는 방법에 대한 단계별 가이드
잘 문서화된 API는 개발자가 API의 목표를 쉽게 이해하고 효율적으로 사용할 수 있음을 의미합니다. 반대로 잘못된 API 문서는 혼란을 야기합니다. 이해하기 쉬운 API 문서를 만드는 데 사용할 수 있는 많은 API 문서 도구가 있습니다.
API 문서란 무엇입니까?
API를 활용하거나 API에 대해 프로그래밍하는 방법을 설명하는 지침 모음을 API 문서라고 합니다. 즉, API 참조 가이드 역할을 합니다. API 문서는 여러 면에서 일반 사용자 매뉴얼과 유사합니다. 따라서 TV, 프린터 등의 기술 제품 매뉴얼에서 사용되는 작문 스타일을 알면 API 문서도 작성할 수 있습니다.
API 문서의 중요성
API 문서는 API를 누구나 이해할 수 있도록 철저하게 설명하기 위한 참고 자료입니다. 또한 사용자가 API에 익숙해지고 사용할 수 있도록 하는 교육 도구의 역할도 합니다.
API 문서는 함수, 매개변수, 반환 유형, 클래스 등을 포함하여 특정 API를 사용하는 데 필요한 모든 세부 정보를 논리적 순서로 제공하는 철저한 안내서입니다. 자료를 더욱 보강하기 위해 설명서는 예제와 교훈도 제공합니다. 성공이 광범위한 채택으로 정의되는 공개 API를 지원하려면 우수한 문서가 필요합니다. 이는 파트너 조직이 이 API와 경쟁자가 제공하는 API 사이에서 결정하는 데 도움이 됩니다.
내부 API에 대한 좋은 문서는 비즈니스 목표를 더 빨리 달성할 수 있도록 합니다. 다른 팀에서 만든 마이크로서비스 API를 빠르게 사용하는 팀의 능력은 회사가 최소 실행 가능 제품을 얼마나 빨리 완료할 수 있는지를 결정합니다. 또한 현재 API 문서는 기존의 정적 프로그램 문서를 훨씬 능가합니다. 사용자에게 보다 매력적인 대화형 문서를 제공할 수 있습니다.
테크니컬 라이팅에서 API 문서란 무엇입니까?
기술 작성자는 수동 또는 자동화 도구를 사용하여 소프트웨어, 하드웨어 또는 웹 API 작동에 대한 포괄적인 정보를 제공하는 API 문서를 작성합니다. 테크니컬 라이터는 효과적인 API 문서를 작성하기 위해 API와 그 기능을 철저히 이해해야 합니다.
대화형 API 문서는 어떻게 만듭니까?
API 문서화는 수동 및 자동화 방식으로 수행할 수 있습니다. 최신 도구를 사용하면 API 문서의 전체 프로세스를 자동화하여 추가 노력 없이 시간을 절약하고 문서를 업데이트 및 유지 관리할 수 있습니다.
API 문서에는 어떤 도구가 사용됩니까?
API 문서를 생성, 유지 관리 및 호스팅하는 데 사용할 수 있는 애플리케이션을 API 문서 도구라고 합니다. 다양한 API 문서 생성기가 존재하며, 그 중 일부는 개발자가 온라인에서 쉽게 읽을 수 있는 놀라운 출력을 생성하는 데 집중합니다. 다른 사람들은 다양한 프로그래밍 언어로 기계가 이해할 수 있고 앱 개발자가 사용할 수 있는 코드 조각을 만드는 데 집중합니다.
상위 6가지 API 문서 도구를 살펴보겠습니다.
1. 슬레이트
Slate는 유연하고, 인지적이며, 매력적인 API 문서를 만들기 위한 훌륭한 도구입니다. 단순하고 사용자 친화적인 디자인은 PayPal 및 Stripe의 API 문서의 영향을 받았습니다. 오른쪽에는 코드 예제가 표시되고 왼쪽에는 설명서가 표시되어 모바일 장치, 태블릿, 랩톱 및 기타 스마트 장치에서 보기 좋고 가독성이 좋습니다.
Slate는 링크를 잃지 않고 모든 정보를 한 페이지에 통합하므로 더 이상 원하는 것을 얻기 위해 끝없는 텍스트 페이지를 통과할 필요가 없습니다. 누군가 스크롤하면 해시가 가장 가까운 헤더로 변경되기 때문에 문서의 특정 섹션에 연결하는 것은 결코 어렵지 않습니다.
2. 앱마스터
AppMaster는 코딩 기술 없이도 API를 포함한 모바일 앱, 웹 앱 및 백엔드를 개발할 수 있는 인기 있는 코드 없는 앱 빌더입니다. 단일 코드 파일을 직접 작성하지 않고도 AppMaster의 도움으로 API 엔드포인트를 생성 할 수 있습니다. 또한 OpenAPI(Swagger) 형식의 API 문서도 자동으로 생성하므로 API 통합 및 문서화 모두에 사용할 수 있습니다.
3. 스웨거
수동 API 문서 대신 Swagger를 사용하면 시간과 노력을 절약할 수 있습니다. API 문서를 개발 및 확인하고 API 변경 사항에 따라 업데이트된 상태로 유지하기 위한 다양하고 우수한 옵션을 제공합니다.
API 사양을 사용하여 문서를 자동으로 생성할 수 있습니다. 오픈 소스 Swagger Inflector를 제공하므로 기존 API에 아직 OpenAPI 정의가 없는 경우 실행 중에도 OpenAPI 정의를 생성할 수 있습니다. Swagger Inspector를 사용하여 엔드포인트에 대한 OpenAPI 파일을 자동으로 생성할 수 있습니다. 그러면 전체 프로세스의 속도가 빨라집니다.
4. 읽어보기
ReadMe는 아름다운 대화형 API 문서를 만들고 관리하기 위한 간단한 방법입니다. API 키는 단순히 페이지에 직접 포함되고 코드 예제는 즉시 생성되며 문제 없이 정품 APU 호출이 가능합니다. 도움말 포럼에 게시된 쿼리에 응답하고 사용자가 일부 개선 사항을 제안하고 모든 사람에게 변경 사항에 대한 정보를 제공하여 강력한 커뮤니티를 만들 수 있습니다. 논문을 최신 상태로 유지하려면 Swagger 파일을 동기화하고 제안된 개선 사항을 결합하고 편집기를 사용하여 콘텐츠를 업데이트하십시오.
5. 재독
ReDoc은 참조 API 문서를 위한 OpenAPI 또는 Swagger 생성 도구입니다. 간단한 배포가 가능하고 문서를 독립적인 HTML 파일로 묶을 수 있습니다. 또한 판별자를 포함한 OpenAPI 2.0 기능을 지원하고 서버 측 렌더링을 제공합니다. 또한 메뉴 또는 스크롤 동기화, OpenAPI 3.0, 코드 예제 및 기타 기능이 있는 반응형 3패널 디자인을 지원합니다. 중첩된 개체에 대한 대화식의 매력적인 문서도 사용할 수 있습니다.
API를 문서화하는 가장 좋은 방법은 무엇입니까?
API를 효율적으로 문서화하기 위해 따라야 하는 특정 전략이 있습니다.
API의 다양한 측면에 익숙해지기
설명하는 API는 개인적으로 익숙해야 합니다. 귀하의 목적은 API에 익숙하지 않을 수 있는 잠재 사용자를 지원하는 것입니다. 문서는 대상 청중의 개념을 혼란스럽게 하는 대신 명확하게 해야 합니다. 제품의 아키텍처, 기능 및 기타 주요 세부 사항을 완전히 이해하고 있다면 API의 제품 설명 섹션을 작성하는 동안 정보에 입각한 추측을 할 필요가 없습니다.
작성 중인 API에 대해 완전히 알지 못하거나 설득력이 없는 경우 시간을 내어 연구를 완료하고 가능한 한 많은 데이터를 컴파일하십시오. API를 직접 사용하여 작동 방식에 대한 중요한 세부 정보를 알아보세요.
관련 콘텐츠에 의존
API 지침은 유일한 종류의 문서가 아닙니다. PowerPoint 프레젠테이션 또는 간단한 클립을 사용하여 API가 통합되는 방법을 설명할 수 있습니다. 문서 초안을 작성하는 동안 많은 사용 사례를 제공합니다. 이를 통해 독자는 자신과 가장 유사한 사례를 식별하거나 연결할 수 있는 사례를 찾을 수 있습니다. 필요한 경우 일부 코드 발췌문도 포함하십시오. 독자들은 이것 때문에 자료를 읽는 동안 따라갈 수 있을 것입니다.
명확성 보장
API는 소프트웨어 또는 하드웨어에 대한 지침이므로 문서에서 기술적인 언어를 사용해야 합니다. 기술적인 콘텐츠를 만들려는 경우 모호하지 않도록 하세요. 좋은 문서는 복잡한 문법 구문을 사용하는 문서보다 관련성 있고 단순하며 명확한 문서입니다. 단순하고 명확한 용어로 표현될 때만 공감할 수 있습니다.
API 문서는 필요한 모든 정보를 포함하면서도 가능한 한 간단해야 합니다. 또한 사용하기 전에 두문자어 및 기술 용어를 정의하거나 가이드 끝에 용어집을 제공하도록 주의하십시오.
구조
자료가 나열되면 문서를 더 쉽게 이해할 수 있습니다. 이것은 간결하게 작성해야 하는 주요 근거입니다. 가이드에 번호가 매겨져 있거나 단계별로 항목화되어 있으면 사용자는 가이드의 각 단계에서 무엇을 해야 하는지 더 잘 이해할 수 있습니다. A에서 Z까지 알파벳을 살펴보는 것과 비슷합니다. 지침이 명확하다면 사용자는 실수를 하면 빠르게 되돌아갈 수 있습니다.
오류 제거
API 문서에서 다양한 유형의 문법, 철자 및 기술 오류를 제거하려면 포괄적인 교정 및 검토 프로세스가 필수적입니다.
API 엔드포인트 문서는 어떻게 작성합니까?
API에 대한 문서는 명확하고 사용자가 쉽게 이해할 수 있어야 합니다. 다음 사항을 염두에 두고 API 엔드포인트 문서를 작성할 수 있습니다.
API의 기능과 관련된 큰 이야기를 선택하고 이를 기반으로 철저한 문서를 작성하십시오.
문서에는 일반적으로 API의 배경 및 소개인 명확한 시작점이 있어야 합니다.
사용자 친화성을 보장하기 위해 표준 구조와 형식을 사용합니다.
독자가 문서와 관련될 수 있도록 사용자의 관점에서 문서를 작성하십시오.
기술적인 사항에 대해 논의할 때 API 문서의 독자가 이러한 용어에 익숙하지 않을 수 있으므로 매우 자세히 설명하십시오.
대화형 API 문서를 만듭니다.
OpenAPI 사양을 사용하여 API 설계를 표준화합니다.
API 문서 예시란 무엇입니까?
이를 분석하기 위해 Google Map API 문서의 예를 들어 보겠습니다.
바쁜 개발자가 원하는 정보를 빠르게 찾아 프로젝트 작업을 계속하려면 뛰어난 탐색 기능이 필수적입니다. Google의 Google 지도 문서의 3열 디자인은 소비자가 원하는 정보를 얻을 수 있는 많은 대안을 제공하는 것을 강조합니다.
테마의 개요는 가장 왼쪽 열에 표시됩니다. 한편 Google은 세 번째 열을 사용하여 사용자가 현재 읽고 있는 기사의 콘텐츠 목록을 표시하고 중간 열에 코드 예제를 배치합니다. 또한 헤더에는 잘 알려진 위치 목록이 포함된 문서용 검색 상자와 드롭다운 메뉴가 있습니다.
문서의 다른 뛰어난 추가 기능으로는 베타 테스트 중인 기능을 나타내는 데 사용되는 플라스크 기호와 밝은 테마에서 어두운 코드 테마로 전환하는 기능이 있습니다.
API 문서에 가장 많이 사용되는 템플릿은 무엇입니까?
API 문서의 표준 템플릿에는 다음 구성 요소가 있습니다.
API의 기능 및 이점에 대한 설명
API가 노출하는 모든 메서드 목록과 각 메서드의 입력 및 출력 그림.
각 메서드에 대한 인수 및 반환 값을 포함한 자세한 기술 정보입니다.
가능한 한 많은 다른 프로그래밍 언어로 생성된 코드 조각을 사용하는 방법을 설명하는 사용자 설명서.
날짜와 함께 모든 API 수정 사항을 나열하는 변경 로그
API의 최신 버전과 같은 버전 세부정보
API를 설치, 구성 및 활용하는 방법을 개발자에게 알려주는 방법 매뉴얼
일반적인 문제를 자세히 설명하고 솔루션을 제공하는 문제 해결 매뉴얼입니다.
사용자 포럼 또는 다른 프로그래머가 작성한 문서를 포함한 관련 웹사이트 목록
문서화에 가장 적합한 소프트웨어는 무엇입니까?
최고의 API 문서 도구라고 선언할 수 있는 특정 도구는 없습니다. 그것은 귀하의 요구 사항과 자동화 또는 수동 도구를 찾고 있는지 여부에 따라 크게 달라집니다. 일반적으로 대부분의 사람들은 사용자 친화적인 인터페이스를 통해 사용할 수 있는 기능을 통해 상당한 유연성과 효율성을 제공하기 때문에 ReDoc과 같은 무료 도구를 사용합니다.
AppMaster와 같은 최신 코드 없는 앱 빌더도 개발 및 문서화 업계에서 두각을 나타내고 있습니다. 코딩 경험이 전혀 없거나 제한적이라고 가정합니다. 이 경우 AppMaster와 같은 플랫폼을 사용하여 최고의 품질과 정확성으로 효율적인 앱 및 API 문서를 개발하는 것이 좋습니다.
결론
결론은 API 문서가 누구에게나 무서운 과정일 필요는 없다는 것입니다. 개발자이든 프로그래머가 아니든 상관없이 AppMaster와 같은 최신 도구를 사용하여 이 프로세스를 진행하고 효과적이고 사용자 친화적인 문서를 만들 수 있습니다.
API 문서 작성하는 방법
728×90
반응형
프로젝트를 진행하면서 API 문서를 작성하는 방법에 대해서 공부했다.
프로젝트 repository wiki에 업로드하여 팀원 모두와 공유하기로 하고 API document를 작성하는 방법에 대해서 검색을 해봤다. 그러던 중 좋은 자료를 발견하였고 이에 맞춰서 wiki를 작성했다.
(자료 출처 : gist.github.com/iros/3426278)
먼저 꼭 들어가야 하는 내용들이다.
API Title – api 이름
URL – api 경로
Method – request 방식 (get | post | delete | put)
Data Params – post 요청시 body안에 넣어줄 값
URL Params (만약 있을 경우) Required – url params로 넘길 값
Success Response – 응답이 성공적으로 반환될 경우 반환되는 값과 코드
Error Response – 응답이 성공적이지 못할 경우 반환되는 값과 코드
Sample Call – 요청과 응답의 예시
다음과 같은 내용들은 꼭 들어가야 하는데 표로 작성해도 좋고 이렇게 글머리 표를 이용해서 작성해도 좋다.
이번에 나는 표를 이용하여 작성해보았다.
예시 자료
마크다운언어로 작성해서 올렸는데 생각보다 썩 이쁘게 나온 거 같지가 않았다.
표의 크기를 조금 수정해서 올리는 것이 좋을 것 같다.
728×90
반응형
[ API ] 프로젝트 API 문서화 DEVLOG
728×90
# Reference
LINE Engineering – 문서 엔지니어링과 API 문서화 by 전정은
https://engineering.linecorp.com/ko/blog/document-engineering-api-documentation/
API 레퍼런스 문서 제작 트렌드 및 도구 조사 by 지단로보트
https://jsonobject.tistory.com/355
백엔드가 이정도는 해줘야 함 – 6.API 스펙 설계와 문서화 방식 결정 – (2) by city7310
https://velog.io/@city7310/%EB%B0%B1%EC%97%94%EB%93%9C%EA%B0%80-%EC%9D%B4%EC%A0%95%EB%8F%84%EB%8A%94-%ED%95%B4%EC%A4%98%EC%95%BC-%ED%95%A8-6.-API-%EC%8A%A4%ED%8E%99-%EC%84%A4%EA%B3%84%EC%99%80-%EB%AC%B8%EC%84%9C%ED%99%94-%EB%B0%A9%EC%8B%9D-%EA%B2%B0%EC%A0%95-2
Restful API 문서 작성 by Peter Kim
https://medium.com/empo-kr/api-%EB%AC%B8%EC%84%9C%EB%A5%BC-%EC%A0%9C%EB%8C%80%EB%A1%9C-%EC%9E%91%EC%84%B1%ED%95%B4%EB%B3%B4%EC%9E%90-feat-insomnia-2a44ee4f0b75
TISTORY OpenAPI
https://tistory.github.io/document-tistory-apis/apis/
0) 학습개요
아대밀맵 서비스가 진짜 얼마 남지 않아 Backend API의 정리가 필요한 시점이 되었습니다.
(사실 이미 해놨어야 하지만 너무 바빠서 미뤄뒀음)
이전까지는 Backend API 문서를 다른 팀원이 작성하거나 그래픽으로 정리해서 줘본 경험밖에 없어서, 이번 기회에 Swagger를 이용하여 일반에 바로 공개할 수 있는 API를 만들어보고자 하였습니다.
1) API 문서화도구 선정
API 레퍼런스를 생성하기 위한 도구는 여러가지가 존재합니다.
——-
1) Slate
마크다운 기반 문서포멧 및 반응형 렌더러 제공.
문서 포맷이 직관적이며 단순.
1개 테마 / 3개 패널 디자인
학습난이도 낮음 | 결과물 세련됨 (최소 노력 최대 결과)
2) API Blueprint
Slate와 유사.
문서 표현가능범위 다양.
렌더러 없음 (Third-party 렌더러 사용이 필요함 (ex: Aglio))
+) Aglio: 5개 테마 / 2, 3패널 디자인 제공
학습난이도 약간 높음 (< Slate) 3) Swagger 가장 유명 JSON & RAML 기반 문서포맷 제공 강력한 REST API 설계철학 강제 => 비준수 서비스: 적용불가
자체 렌더러 존재 (Swagger UI), 유명한 Third-party 렌더러 존재 (ReDoc, 3패널 디자인)
4) GitBook
깔끔한 UI 제공
Git의 commit / merge가 존재 -> 문서 버전 관리 가능 (=업데이트 내역 확인 용이)
테스트 요청 / 응답 사용 불가
팀이 사용할 경우 유료 (개인은 무료)
——-
저는 이중 GitBook을 사용했고, 이유는 다음과 같습니다.
1) API로 공개하는 정보를 사용할 대상이 제한적임 (아주대학교 내에서 인근 음식점 정보를 활용한 개발 프로젝트를 진행하고자 하는 학우)
2) 테스트 요청을 지원해야하는 필요성이 크지 않음 (1과 상동)
3) 개인 프로젝트이므로 API 문서 작성이 무료
2) Gitbook 둘러보기
GitBook에 가입하고 난 뒤 API Docs를 선택 후 진행했습니다.
API문서 생성이 완료되었습니다. 양이 많아 한번에 작성하진 못했고, user api만 업로드 했습니다.
지속적으로 업데이트 하며 서비스 공개 직후 공개 할 예정입니다.
https://nate-crema.gitbook.io/aj-mealmap-api/
——–|Updated
2021.11.13 | 문서 신규생성
728×90
반응형
매개변수 :: Technical Writing blog
매개변수 예시 살펴보기
매개변수(Parameter)는 엔드포인트와 함께 전달할 수 있는 옵션이다. 헤더 매개변수, 경로 매개변수 및 쿼리 문자열 매개변수와 같은 여러 유형의 매개변수가 있다. 매개변수의 예시는 다음과 같다. 토스 페이먼츠에서는 문서 옆에 코드 예제를 같이 보여주기 때문에 표를 더 간단하게 작성한 것 같다. Type이나 Required 열을 별도로 두지 않고 parameter name 아래에 같이 작성한 것을 확인할 수 있다.
출처: 토스페이 API가이드
API문서에서 매개변수들은 대부분 아래 표 형태에서 크게 벗어나지 않는다.
Parameter Required/Optional Description Data Type format Optional – String
문서 작성 시 주의해야 할 사항
매개변수 유형에 관계없이 각 매개변수에 대해 데이터 형식과 최대값, 최소값을 정의해야 한다.
매개변수의 데이터 유형
카카오 디벨로퍼 문서에서는 Type 열에서 매개변수의 유형을 명시하고 있다. 토스페이 API가이드에서는 매개변수 명 아래에 Type을 명시해주었다. API가 잘못된 데이터 유형 또는 잘못된 형식인 경우 매개변수를 올바르게 처리하지 못할 수 있으므로 매개변수의 데이터 유형을 작성해줘야 한다. 매개변수의 데이터 유형에는 String, ingterger, bollean, object, array 등이 올 수 있다.
매개변수의 최대값과 최소값
매개변수는 최대값과 최소값 또는 허용되는 값을 나타내야 한다. 예를 들어 날씨 API가 특정 국가의 경도 및 위도 좌표만 허용하는 경우 문서에 작성되어 있어야 한다.
그러나 모든 매개변수에 최대값과 최소값이 필요한 것은 아니다.
– Booleans를 사용하는 경우 true 또는 false이므로 최대 최소값이 필요 없다.
– 열거형을 사용하는 문자열의 경우에는 허용되는 값들을 명시해줄 수 있다.
즉, 필드에 적용되는 제한을 알아야 하고 제한이 있다면 API문서에 작성해줘야 한다.
요청(Request) 문서화하기
아래는 API 문서에서 오른쪽에 Example Request라는 항목이 보인다. 토스페이 API문서에서는 이처럼 가이드 문서에 요청 예시를 같이 보여주고 있다. (나 같은 초보자(?)는 이해하기가 훨씬 수월하다! 직관적으로 보이는 것 같기도 하고!) 아래 요청 예시는 JSON형식이다. JSON은 여러 수준의 중첩이 있는 key(키) : value(값) 의 쌍으로 이루어진 데이터 객체로 이루어져 있다.
출처: 토스페이 API가이드
요청과 응답 모두에서 JSON 데이터를 문서화하는 것은 API문서에서 까다로운 부분 중에 하나라고 한다. 동일한 수준의 몇 개의 키-값 쌍만 객체는 문서화하는 것이 쉽겠지만 객체 안에 여러 객체가 있거나, 다양한 중첩이 있는 경우에는 나타내기가 어렵다. JSON 객체가 100줄 또는 1000줄 이상에 걸쳐 있는 경우도 있다고 하는데 이럴 때는 정보를 표시하는 방법에 대해서 신중하게 생각해야 한다. (이런 정보를 쉽고 간단하게 표현하는 게 IT업계에서 TW가 하는 일이 아닐까?)
아래 이미지는 Swagger Petstore의 예시이다. 여기에서도 단순히 표 형태로 나열하는 것 외에도 토글을 클릭하면 요청 예시를 볼 수 있다. Model 탭을 클릭하면 샘플 요청 본문과 각 요소에 대한 설명도 나타난다.
출처: Swagger petstore 데모
요청 본문을 문서화할 때 올바른 방법이 정해져 있는 것이 아니다. API의 매개변수를 가장 명확하고 읽기 쉬운 방식으로 설명하는 것이 중요하다고 말한다.
그럼 다시 실습 예제로 돌아와서 이전 포스팅에 작성했던 예제에 매개변수를 추가해서 다음과 같이 작성해보았다. 위키 페이지를 토대로 작성해보았는데 이게 최선인지는 알 수가 없어서 아쉽다.😂
(units항목은 단위를 입력해야 하니까 string형식이 맞는 걸까? 혹시 누군가 이 포스팅을 보다가 틀린 점이 있다면 댓글로 남겨주세요!)
Surfreport
서핑 높이와 조수 및 바람을 포함한 서핑 조건에 대한 정보를 포함합니다. 이 정보로 서퍼가 서핑을 하기에 적절한 조건인지 알려줄 수 있습니다.
EndPoint
GET Surfreport/{beachId}
beachId 로 특정 해변의 서핑 조건을 가져옵니다.
Path parameter
Name Description {beachId} 해변의 ID값
{beachId}는 사이트의 해변 목록에서 검색됩니다. Query string parameter
Name Type Required Description days Integer X 응답에 포함할 일 수입니다. 기본값은 3입니다. 최대로 볼 수 있는 일 수는 7입니다. time Integer
UTC의 Unix형식 X 시간을 포함하면 현재 시간만 응답으로 반환합니다. units string X 측정 단위입니다. metric(야드 파운드 법)과 imperial(미터법) 단위를 사용할 수 있습니다. 값이 없으면 standard 단위가 기본값으로 적용됩니다.
요즘 다양한 API문서들을 보다 보면 이런 식으로도 작성할 수 있구나!라는 것을 배워가고 있다.😉 하지만 직접 작성해보는 것은 어렵다..!
키워드에 대한 정보 api 문서 예시
다음은 Bing에서 api 문서 예시 주제에 대한 검색 결과입니다. 필요한 경우 더 읽을 수 있습니다.
이 기사는 인터넷의 다양한 출처에서 편집되었습니다. 이 기사가 유용했기를 바랍니다. 이 기사가 유용하다고 생각되면 공유하십시오. 매우 감사합니다!
사람들이 주제에 대해 자주 검색하는 키워드 초보 개발자의 좌충우돌 API 문서 만들기
- 코드스테이츠
- API문서
- 초보개발자
- codestates
초보 #개발자의 #좌충우돌 #API #문서 #만들기
YouTube에서 api 문서 예시 주제의 다른 동영상 보기
주제에 대한 기사를 시청해 주셔서 감사합니다 초보 개발자의 좌충우돌 API 문서 만들기 | api 문서 예시, 이 기사가 유용하다고 생각되면 공유하십시오, 매우 감사합니다.