방금 새 홈 시어터 시스템을 구입하고 설치하러 간다고 상상해 보십시오. 무엇을 먼저 합니까? 감사합니다. 도움이 되는 편리한 장치 설명서가 있습니다. 설명서에 설명된 단계를 따르기만 하면 됩니다. 짜잔! 홈 시어터 시스템이 좋아하는 노래를 불러올 준비가 되었습니다. 장치 설명서가 설정 및 설치를 안내하는 것처럼 API 설명서는 API 구성을 안내하는 데 도움이 될 수 있습니다.
API 문서란 무엇입니까?
API 문서에 대해 알아보기 전에 API가 무엇이며 기본 기능에 대해 간략하게 설명하겠습니다. API는 Application Programming Interface의 약자입니다.
API를 통해 데이터베이스에 장치 연결
초보자 코더이든 고급 개발자이든 소프트웨어 개발 과정에서 이 용어를 자주 접하게 됩니다. 컴퓨터, 휴대폰 또는 응용 프로그램과 외부 리소스를 연결하는 다리입니다. 즉, API는 소프트웨어에 다른 소프트웨어 프로그램, 데이터베이스 또는 리소스와 상호 작용할 수 있는 기능을 제공합니다. 애플리케이션의 특정 기능에 대한 프로그램을 작성하는 대신 유사한 기능의 즉시 사용 가능한 API를 사용할 수 있습니다. 많은 API는 공개(무료)이고 다른 API는 비공개이며 API에 액세스할 수 있도록 하는 개인 키에 대한 비용을 지불해야 합니다. REST(Representational State Transfer), SOAP(Simple Object Access Protocol) 등과 같은 다양한 유형의 API가 있습니다. 계속해서 – API 문서란 무엇입니까? API의 기능, 프로그램에 통합하는 방법, API 사용 사례를 예제와 함께 설명하는 서면 가이드입니다. API 문서는 기술적인 내용임을 명심하십시오. 이것은 몇 가지 기술 용어를 포함하지만 여전히 읽기 쉽고 이해하기 쉬워야 함을 의미합니다.
누가 API 문서를 작성해야 합니까?
API는 소프트웨어 개발자가 만듭니다. 소프트웨어 개발자는 API 구축 및 사용에 직접 관여하기 때문에 문서 작성이 더 쉽습니다. API 문서를 작성하는 소프트웨어 개발자의 단점은 매우 기술적인 각도에서 작성하여 문서를 이해하기 어렵게 만들 수 있다는 것입니다. 또 다른 문제는 API 개발자가 API를 개발하면서 문서를 작성하는 데 더 많은 시간이 걸린다는 것입니다. 따라서 좋은 대안은 API 문서화 작업을 기술 작성자에게 할당하는 것입니다. 테크니컬 라이터는 콘텐츠 작성의 전문성과 기술적 지식을 결합하여 기술적인 것뿐만 아니라 유익하고 이해할 수 있는 문서를 작성하는 사람입니다. 테크니컬 라이터는 API 개발자로부터 API에 대해 배운 다음 문서화 목적으로 자습서, 예제 및 기타 콘텐츠를 만듭니다. 한편 API 개발자는 기술 작성자를 감독하여 작성된 문서가 정확한지 확인하고 필요한 경우 작성자에게 추가 정보를 제공할 수 있습니다. 목표는 API를 완전히 설명하고 혼란 없이 사용자를 안내하는 문서를 만들기 위해 모든 사람이 협력하는 것입니다. API에 대한 문서 작성에 관심이 있지만 어디서, 어떻게 시작해야 할지 모르겠다면 이 문서가 시작하는 데 도움이 될 것입니다. 여기에서 당신의 흥분을 느낄 수 있습니다, 그래서 잠수하자!
API 문서 작성을 시작하는 방법
API 문서를 작성할 때 여러 개요를 작성하는 것으로 시작하십시오. 이것은 당신이 쓰고자 하는 것에 대한 개요를 줄 것입니다. 다음은 생성한 각 개요에 대한 정보를 수집하는 것입니다. 이는 API 개발자로부터 API 설명, 사용된 언어, 기타 참조 및 샘플 사례를 얻어서 달성할 수 있습니다. API의 라이브 데모를 보고 작동 방식을 직접 경험할 수도 있습니다. 마지막으로 수집한 세부 정보를 결합하고 논리적인 순서로 정렬합니다. 공개하기 전에 문서를 교정하고 수정하거나 추가할 수 있도록 API 개발자와 공유하는 것을 잊지 마십시오. 이제 어디서부터 시작해야 하는지 알았으니 의미 있는 전체가 되도록 비트를 어떻게 조합할 수 있습니까?
API 문서에 포함할 사항
1. 개요
이것은 프로젝트 보고서의 요약 페이지와 유사합니다. 개요에는 API의 요약과 API가 해결하는 문제가 포함되어야 합니다. 다른 유사한 API보다 이 특정 API를 사용하는 이점도 포함될 수 있습니다.
2. 튜토리얼
이것은 문서의 주요 부분입니다. 여기에는 API의 개념을 사용자에게 설명하는 데 사용하는 다양한 콘텐츠 형식이 포함되어야 합니다. 또한 참조용 링크와 API를 통합하고 올바르게 작동하도록 사용하기 위한 단계별 가이드를 포함할 수 있습니다.
3. 예
API 작동 방식 및/또는 항목별 단계를 제공한 후에는 개발자가 API와 상호 작용하는 방식과 관련된 호출, 응답, 오류 처리 및 기타 작업의 예를 보여주는 것이 좋습니다.
4. 용어집
이것은 선택 사항이지만 API 문서에 대한 용어집 페이지를 추가하는 것이 좋습니다. 긴 텍스트 블록으로 사용자의 지루함을 피하기 위해 문서 전체에서 사용하는 다양한 용어, 스키마, 이미지 등의 설명을 모두 용어집에 푸시할 수 있습니다. 그런 다음 문서에서 이러한 항목을 참조하고 용어집에 연결할 수 있습니다.
유용한 API 문서 작성 방법
API 알기
방금 논의한 대로 문서화하는 API에 대한 직접적인 지식이 있어야 합니다. 귀하의 목표는 API에 대한 지식이 없을 수도 있는 잠재적 사용자를 안내하는 것임을 기억하십시오. 당신은 그들을 혼동하고 싶지 않을 것입니다, 그렇죠? 제품의 아키텍처, 기능 및 기타 중요한 정보를 확실히 이해하고 있다면 추측하지 않고도 API의 제품 설명 부분을 효과적으로 작성할 수 있습니다. 작성 중인 API에 대해 잘 알지 못하거나 완전히 확신하지 못한다면 시간을 내어 조사를 하고 가능한 한 많은 정보를 수집하십시오. API를 직접 사용하여 작동 방식에 대한 중요한 통찰력을 얻으십시오.
관련 콘텐츠 사용
API 문서는 서면 가이드에만 국한되지 않습니다. 짧은 비디오나 PowerPoint 슬라이드를 사용하여 API 통합을 설명할 수 있습니다. 문서를 작성하는 동안 다양한 사용 사례를 설명합니다. 이렇게 하면 독자가 자신과 유사한 것을 인식하거나 쉽게 공감할 수 있는 것을 찾는 데 도움이 됩니다. 또한 필요하다고 생각되는 위치와 시간에 일부 코드 스니펫을 포함하십시오. 이렇게 하면 독자가 설명서를 따라갈 수 있습니다. 유명한 속담처럼 "말하면 잊겠습니다. 가르쳐 주시면 기억하겠습니다. 참여하면 배우겠습니다."
기술이 필요한 경우에도 명확하게 하십시오.
API는 소프트웨어 또는 하드웨어에 대한 가이드이므로 문서를 작성할 때 몇 가지 기술 용어를 사용해야 합니다. 기술 작가가 되려는 경우 모호해지고 싶은 유혹을 물리치십시오. 좋은 문서는 복잡한 문법 구조를 가진 문서가 아니라 관련성이 있고 간단하며 명확한 문서입니다. 단순하고 이해하기 쉬운 언어로 쓰여져야만 공감할 수 있습니다. API 문서는 가능한 가장 간단한 형식이어야 하지만 중요한 세부 정보를 빠뜨리지 않아야 합니다. 또한 처음 사용할 때 두문자어 및 기술 용어를 설명하거나 설명서 끝 부분의 용어집에 넣어야 합니다.
가이드 항목화
내용을 항목별로 정리하면 문서를 더 쉽게 이해할 수 있습니다. 이것이 간결하게 작성해야 하는 주요 이유입니다. 가이드에 번호를 매기거나 항목을 단계별로 지정하면 사용자가 모든 시점에서 수행할 작업을 파악하는 데 도움이 됩니다. 알파벳 A부터 Z까지 읽는 것과 비슷합니다. 명확한 단계를 통해 사용자는 오류가 발생할 경우 쉽게 돌아갈 수 있습니다.
오류 확인
문서를 여러 번 읽으면 항상 변경, 업데이트 또는 삭제할 항목이 있습니다. 이것은 작가들의 전형적인 경험이며 당신을 화나게 해서는 안됩니다. 금은 정제되기 전에 여러 불타는 용광로를 거칩니다. 문서가 유사한 프로세스(불같은 용광로는 아니지만)를 거쳐야 잘 준비된 문서로 나온다고 가정해 보겠습니다. 철저한 검토 프로세스를 통해 오류를 최소화하고 명확한 문서를 작성할 수 있습니다. API 문서 작성은 시간이 많이 걸리고 유지 관리하기 어려울 수 있습니다. 그러나 좋은 문서 도구는 이러한 문제의 전부는 아니더라도 대부분을 완화할 수 있습니다. API 문서화 과정을 더 쉽게 만들어주는 수많은 도구가 있습니다. 도구 사용의 이점은 처음부터 시작하지 않고 이러한 도구가 제공하는 공동 작업 기능과 표준 템플릿입니다. 다음은 몇 가지 인기 있는 도구와 그 장점의 목록입니다.
우편 집배원
Postman은 API 문서 작성을 위한 기능으로 API를 구축 및 유지 관리하기 위한 플랫폼입니다. Postman은 기계가 읽을 수 있는 문서 도구를 사용하여 API 문서 프로세스를 더 쉽고 빠르게 만듭니다. Postman에 무료로 가입하여 PC에 설치할 수 있습니다. Postman은 자동으로 생성하는 모든 API 문서에 대한 업데이트를 제공하지만 해당 UI는 처음에는 이해하기 어려울 수 있습니다.
대퍼독스
DapperDox는 문서 작성을 위한 다양한 테마를 제공하는 오픈 소스 API 문서 도구입니다. 이 도구는 다이어그램, 사양 및 기타 콘텐츠 유형을 결합하여 더 나은 문서를 제공합니다. 작성자가 GitHub 풍미 마크다운으로 작성할 수 있다는 이점이 있지만 이 도구에 대한 업데이트는 불규칙합니다.
SwaggerHub
SwaggerHub는 대화형이고 사용하기 쉽기 때문에 많은 기술 작성자에게 인기 있는 API 문서 도구입니다. 초보자 친화적이지만 개인 사용 이외의 모든 비용을 지불해야 합니다. 따라서 조직의 일원이고 SwaggerHub를 사용하려는 경우 조직에서 비용을 지불해야 합니다. 여기에 나열된 도구를 선택하든 대안을 선택하든 다음을 고려해야 합니다.
어떤 설정에서 도구를 사용합니까? 개인용입니까 아니면 조직의 일부입니까?
당신은 얼마나 기술적인가? 당신은 초보자 또는 전문가입니까?
사용자 인터페이스와 사용자 경험은 어떻습니까?
API 문서의 몇 가지 멋진 예
다음은 훌륭한 API 문서 작성을 시작하는 데 영감을 줄 몇 가지 API 문서입니다. 이러한 각 문서는 쉬운 단계와 이해하기 쉬운 용어로 개발자에게 제품 API 사용을 자세히 설명합니다.
GitHub API 문서
GitHub는 정말 유용한 문서를 제공합니다. 이는 놀라운 일이 아닙니다. 여기에서 API 문서를 확인하세요.
REST API 시작하기 - GitHub Docs 인증 및 일부 엔드포인트 예제부터 시작하여 REST API 사용을 위한 기초를 알아보세요.
REST API는 개발자가 웹 또는 데이터베이스의 데이터에 액세스하는 데 사용하는 인기 있는 API입니다. Github의 이 문서에는 프로그램에서 REST API를 사용하는 방법에 대한 개요, 가이드 및 코드가 포함되어 있습니다. 이 문서의 흥미로운 부분은 기술 수준에 관계없이 쉽게 이해할 수 있다는 것입니다.
Paystack API 문서
집 Paystack API로 놀라운 결제 경험 구축
결제가 필요한 애플리케이션을 만들고 있습니까? Paystack은 결제를 위한 핀테크 솔루션입니다. 그들의 팀은 개발자에게 프로그램에서 Paystack API를 사용하는 방법에 대한 자세한 정보를 제공합니다. API를 프로그램에 사용할 때 혼동을 피하기 위해 API 사용에 대한 핸드북을 제공하는 것과 비슷합니다.
트위터 API 문서
트위터 API 문서 Twitter에서 대화를 프로그래밍 방식으로 분석하고, 학습하고, 참여하세요. 지금 Twitter API 문서를 살펴보십시오.
Twitter API 설명서는 개발자가 앱과 상호 작용할 수 있는 방법을 설명합니다. 문서에는 다양한 섹션(사용자, 트윗, 다이렉트 메시지 등)과 해당 작업이 명확하게 자세히 설명되어 있습니다. 더 많은 정보를 위해서는 권한 접근이 필요하지만, 링크를 클릭하면 기본 정보에 접근할 수 있습니다.
결론
문서에는 다른 사람들이 올바르게 사용할 수 있도록 도구가 작동하는 방식이 나와 있습니다. API 문서를 만드는 것이 항상 쉬운 것은 아니지만 유용한 문서를 만드는 것은 생각만큼 어렵지 않습니다. 기억하십시오. 첫 번째 초안을 작성하는 것으로 시작하여 매일 개선하고, 막혔을 때 멘토나 고위 동료의 도움을 구하십시오. 이제 다음 세계 정상급 제품과 함께 제공될 API 문서를 작성하십시오.
댓글