API 설명서 만들기

소스 코드 리포지토리에 대한 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 설명서를 만드는 프로세스를 더 쉽게 만들 수 있습니다. 인기 있는 선택으로는 지킬, MkDocs, 도쿠사우루스, 휴고 등이 있습니다. 생성기를 설정하여 Markdown 파일을 읽고 정적 HTML 페이지를 만듭니다. 레이아웃, 테마 및 스타일을 프로젝트의 브랜딩 및 기본 설정에 맞게 사용자 지정할 수 있습니다.

HTML 콘텐츠를 게시하려면 GitHub 페이지를 사용하여 GitHub 리포지토리에서 직접 정적 웹 사이트를 호스트할 수 있습니다. 이 용도로 전용 분기를 만들고 HTML 파일을 이 분기에 푸시할 수 있습니다. 또한 GitHub Actions를 사용하여 설명서 파일 또는 코드가 변경되면 API 설명서를 자동으로 빌드하고 배포할 수 있습니다.

문서 파일 또는 코드가 변경되면 API 설명서를 자동으로 빌드하고 배포하도록 GitHub Actions를 설정합니다. 선택한 설명서 생성기를 사용하여 HTML 설명서 파일을 만들고 GitHub Pages에 배포하도록 자동화 워크플로를 구성합니다.