API 설명서 생성
API를 유지 관리하고 사용하는 개발자에게 명확성, 접근성 및 사용 편의성을 제공하려면 소스 코드 리포지토리의 API를 문서화하는 것이 필수적입니다. 포괄적인 설명서는 API 엔드포인트의 기능, 입력, 출력 및 사용법을 이해하기 위한 가이드 역할을 합니다. API를 문서화할 때 예 및 사용 시나리오가 포함된 가장 적합한 프레젠테이션 형식(예: OpenAPI 사양 또는 Markdown)을 선택하고, 코드 변경 내용을 최신 상태로 보관하고, API 소비자의 피드백을 요청하여 품질을 지속적으로 개선해야 합니다.
API 문서화에 대한 일반적인 방식은 플랫폼에 구애받지 않지만 Azure DevOps와 GitHub 간의 구현에는 몇 가지 차이점이 있습니다.
Azure DevOps에서 API 문서화
가장 효율적인 방식으로 Azure DevOps 프로젝트에 API 설명서를 추가하려면 개발 워크플로와 통합되는 전용 설명서 도구 또는 플랫폼을 활용하는 것을 고려해야 합니다. 이 범주에서 자주 사용되는 선택에는 Swagger(OpenAPI), API Blueprint 및 MkDocs 또는 Docusaurus와 같은 Markdown 기반 설명서 시스템이 포함됩니다. Azure DevOps 통합 기능은 설명서 생성 프로세스를 자동화하여 코드베이스와 동기화를 유지하는 데 도움이 됩니다. 대부분의 설명서 도구는 인라인 주석 구문 분석 및 자동 생성 설명서에 포함하는 기능도 지원합니다.
팀 멤버와 관련자가 액세스할 수 있는 중앙 위치에 API 설명서를 게시해야 합니다. 이는 전용 설명서 웹 사이트, Azure DevOps 내의 Wiki 또는 외부 설명서 포털일 수 있습니다.
또는 코드 내에서 직접 코드 주석이나 데코레이터를 사용하여 API 엔드포인트를 설명하는 메타데이터를 추가할 수 있습니다. Swagger Codegen 또는 Springfox와 같은 도구는 이러한 주석을 처리하고 OpenAPI 사양 파일을 생성할 수 있습니다.
코드베이스가 변경될 때마다 자동으로 API 설명서를 생성하도록 Azure Pipelines 내에서 자동화된 프로세스를 설정합니다. 이렇게 하면 설명서가 최신 상태로 유지되고 API의 최신 변경 내용이 반영됩니다.
Github에 API 문서화
GitHub를 사용할 때 GitHub 에코시스템의 일부인 도구를 활용하여 API 설명서를 생성하는 것이 좋습니다.
먼저 API 엔드포인트, 작업, 매개 변수, 응답 및 기타 관련 정보를 문서화합니다. 광범위한 지원과 사용 편의성을 고려하여 해당 설명서를 Markdown 형식으로 작성하는 것이 좋습니다. 인증, 엔드포인트, 요청 매개 변수, 응답 예 등을 설명하는 섹션으로 나누어 개별 문서의 일관된 구조를 정의합니다.
Azure DevOps와 마찬가지로 설명서 생성기 또는 정적 사이트 생성기를 사용하여 Markdown 파일에서 API 설명서를 생성하는 프로세스를 간소화할 수 있습니다. 자주 사용되는 선택에는 Jekyll, MkDocs, Docusaurus 및 Hugo가 있습니다. Markdown 파일을 구문 분석하고 정적 HTML 페이지를 생성하도록 생성기를 구성합니다. 프로젝트의 브랜딩 및 선호도에 맞게 레이아웃, 테마 및 스타일을 사용자 지정할 수 있습니다.
HTML 콘텐츠를 게시하려면 GitHub 페이지를 활용하여 GitHub 리포지토리에서 직접 고정적인 웹 사이트를 호스트할 수 있습니다. 이 목적을 위해 전용 분기를 만들고 HTML 파일을 이 분기에 푸시할 수 있습니다. 설명서 파일이나 코드베이스가 변경될 때마다 GitHub Actions를 구현하여 API 설명서를 자동으로 빌드하고 배포할 수도 있습니다.
설명서 파일 또는 코드베이스가 변경되면 API 설명서를 자동으로 빌드하고 배포하도록 GitHub Actions를 설정합니다. 선택한 설명서 생성기를 사용하여 HTML 설명서 파일을 생성하고 GitHub 페이지에 배포하도록 자동화 워크플로를 구성합니다.