Visual Studio Code용 Azure API 센터 확장을 사용하여 API 빌드 및 등록

API 센터에서 API를 빌드, 검색, 탐색 및 사용하려면 Visual Studio Code 개발 환경에서 Azure API 센터 확장을 사용할 수 있습니다. 이 확장은 API 개발자를 위해 다음과 같은 기능을 제공합니다.

• 빌드 API - API 센터에 직접 등록하거나 GitHub 또는 Azure DevOps에서 CI/CD 파이프라인을 사용하여 빌드하는 API를 다른 사용자에게 검색할 수 있도록 합니다. 통합 Linting 지원을 통해 Shift-left API 디자인 적합성을 Visual Studio Code로 확인합니다. 호환성이 손상되는 변경 검색을 통해 새로운 API 버전이 API 소비자를 손상시키지 않는지 확인합니다.

• API 검색 - API 센터에서 API를 찾아보고 세부 정보와 문서를 봅니다.

• API 탐색 - Swagger UI 또는 REST 클라이언트를 사용하여 API 요청 및 응답을 탐색합니다.

• API 사용 - Microsoft Graph, GitHub 등에 사용되는 SDK를 생성하는 Microsoft Kiota 엔진을 사용하여 JavaScript, TypeScript, .NET, Python 및 Java를 포함한 원하는 언어에 대한 API SDK 클라이언트를 생성합니다.

필수 조건

• Azure 구독에 하나 이상의 API 센터가 있습니다. 아직 API 센터를 만들지 않았다면 빠른 시작: API 센터 만들기를 참조하세요.

  현재 확장을 사용하여 API 센터를 관리하려면 기여자 역할 이상의 권한을 할당받아야 합니다.

• Visual Studio Code

• Visual Studio Code용 Azure API 센터 확장

  참고 항목

  명시된 경우 특정 기능은 확장의 시험판 버전에서만 사용할 수 있습니다. Visual Studio Code Marketplace의 확장을 설치할 때는 릴리스 버전 또는 시험판 버전을 설치하도록 선택할 수 있습니다. 확장 보기에서 확장의 관리 단추 상황에 맞는 메뉴를 사용하여 언제든지 두 버전 간을 전환합니다.

다음 Visual Studio Code 확장은 선택 사항이며 표시된 대로 특정 시나리오에만 필요합니다.

• REST 클라이언트 확장 - HTTP 요청을 보내고 Visual Studio Code에서 직접 응답을 봅니다.
• Microsoft Kiota 확장 - API 클라이언트를 생성합니다.
• Spectral 확장 - Visual Studio Code에서 Shift-left API 디자인 적합성 검사를 실행합니다.
• Optic CLI - API 사양 문서 간의 호환성이 손상되는 변경 검색
• GitHub Copilot - API 코드에서 OpenAPI 사양 파일 생성

설정

1. Visual Studio Code Marketplace에서 Visual Studio Code용 Azure API 센터 확장을 설치합니다. 필요에 따라 선택적 확장을 설치합니다.
2. Visual Studio Code의 왼쪽 작업 표시줄에서 API 센터를 선택합니다.
3. Azure 계정에 로그인되어 있지 않은 경우 Azure에 로그인...을 선택하고 프롬프트에 따라 로그인합니다. API를 보려는 API 센터(또는 API 센터)가 있는 Azure 계정을 선택합니다. 볼 구독이 많은 경우 특정 구독을 필터링할 수도 있습니다.

API 등록

API를 일회성 작업으로 등록하거나 CI/CD 파이프라인을 사용하여 Visual Studio Code에서 직접 API 센터에 등록합니다.

1. 명령 팔레트를 열려면 Ctrl+Shift+P 바로 가기 키를 사용합니다. Azure API Center: API를 등록하고 Enter 키를 누릅니다.

2. API 센터에 API를 등록하는 방법을 선택합니다.

   • 단계별은 API를 일회용으로 등록하는 데 가장 적합합니다.
   • CI/CD는 소스 제어에 대한 각 커밋에서 CI/CD 워크플로의 일부로 실행되는 활성 Visual Studio Code 작업 영역에 사전 구성된 GitHub 또는 Azure DevOps 파이프라인을 추가합니다. 시간이 지남에 따라 API가 계속 발전함에 따라 사양 및 버전을 포함한 API 메타데이터가 API 센터에서 최신 상태로 유지되도록 CI/CD를 사용하여 API 센터에 API 인벤토리를 작성하는 것이 좋습니다.

3. 등록 단계 완료:

   • 단계별에서는 API를 등록할 API 센터를 선택하고 API 제목, 형식, 수명 주기 단계, 버전, 사양 등의 정보가 포함된 프롬프트에 답변하여 API 등록을 완료합니다.
   • CI/CD의 경우 기본 소스 제어 메커니즘에 따라 GitHub 또는 Azure DevOps를 선택합니다. 작업 영역에 파이프라인을 추가하려면 Azure API 센터 확장에 대해 Visual Studio Code 작업 영역이 열려 있어야 합니다. 파일이 추가된 후 CI/CD 파이프라인 파일 자체에 설명된 단계를 완료하여 Azure Pipeline/GitHub 작업 환경 변수 및 ID를 구성합니다. 소스 제어에 푸시하면 API가 API 센터에 등록됩니다.

   API 센터에 API를 등록하도록 GitHub Actions 워크플로 를 설정하는 방법에 대해 자세히 알아봅니다.

API 디자인 적합성

API를 빌드할 때 조직 표준에 대한 디자인 준수를 보장하기 위해 Visual Studio Code용 Azure API 센터 확장은 Spectral을 사용한 API 사양 린팅에 대한 통합 지원을 제공합니다.

1. 명령 팔레트를 열려면 Ctrl+Shift+P 바로 가기 키를 사용합니다. Azure API Center: 활성 API 스타일 가이드 설정을 입력하고 Enter 키를 누릅니다.
2. 제공된 기본 규칙 중 하나를 선택하거나, 조직에 이미 사용 가능한 스타일 가이드가 있는 경우 로컬 파일 선택 또는 원격 URL 입력을 사용하여 Visual Studio Code에서 활성 규칙 집합을 지정합니다. Enter 키를 누릅니다.

활성 API 스타일 가이드가 설정되면 OpenAPI 또는 AsyncAPI 기반 사양 파일을 열면 Visual Studio Code에서 로컬 린팅 작업이 트리거됩니다. 결과는 편집기와 문제 창(보기>문제 또는 Ctrl+Shift+M)에 모두 표시됩니다.

호환성이 손상되는 변경 검색

새 버전의 API를 도입할 때 도입된 변경 내용으로 인해 이전 API 버전의 API 소비자가 중단되지 않는지 확인해야 합니다. Visual Studio Code용 Azure API 센터 확장을 사용하면 Optic에서 제공하는 OpenAPI 사양 문서에 대한 호환성이 손상되는 변경 검색을 통해 이를 쉽게 수행할 수 있습니다.

1. 명령 팔레트를 열려면 Ctrl+Shift+P 바로 가기 키를 사용합니다. Azure API Center: 호환성이 손상되는 변경 검색를 입력하고 Enter 키를 누릅니다.
2. 비교할 첫 번째 API 사양 문서를 선택합니다. 유효한 옵션에는 API 센터, 로컬 파일 또는 Visual Studio Code의 활성 편집기에 있는 API 사양이 포함됩니다.
3. 비교할 두 번째 API 사양 문서를 선택합니다. 유효한 옵션에는 API 센터, 로컬 파일 또는 Visual Studio Code의 활성 편집기에 있는 API 사양이 포함됩니다.

Visual Studio Code는 두 API 사양 간의 차이점 보기를 엽니다. 호환성이 손상되는 변경은 편집기와 문제 창(보기>문제 또는 Ctrl+Shift+M)에 모두 표시됩니다.

API 코드에서 OpenAPI 사양 파일 생성

Visual Studio Code용 Azure API 센터 확장과 함께 GitHub Copilot의 기능을 사용하여 API 코드에서 OpenAPI 사양 파일을 만듭니다. API 코드를 마우스 오른쪽 단추로 클릭하고 옵션에서 Copilot을 선택하고 API 생성 설명서를 선택합니다. 그러면 OpenAPI 사양 파일이 생성됩니다.

OpenAPI 사양 파일을 생성하고 정확도를 확인한 후 Azure API Center: Register API 명령을 사용하여 API를 API 센터에 등록할 수 있습니다.

API 검색

API 센터 리소스가 왼쪽 트리 뷰에 표시됩니다. API 센터 리소스를 확장하여 API, 버전, 정의, 환경 및 배포를 확인합니다.

API 트리 뷰 항목에 표시된 검색 아이콘을 사용하여 API 센터 내에서 API를 검색합니다.

API 문서 보기

API 센터에서 API 정의 문서를 보고 API 작업을 시도할 수 있습니다. 이 기능은 API 센터의 OpenAPI 기반 API에서만 사용 가능합니다.

1. API 센터 트리 뷰를 확장하여 API 정의를 표시합니다.

2. 정의를 마우스 오른쪽 단추로 클릭하고 API 문서 열기를 선택합니다. API 정의에 대한 Swagger UI가 있는 새 탭이 표시됩니다.

   

3. API를 시도하려면 엔드포인트를 선택하고 사용해 보기를 선택하고 필수 매개 변수를 입력한 다음, 실행을 선택합니다.

   참고 항목

   API를 시도하려면 API에 따라 권한 부여 자격 증명이나 API 키를 제공해야 할 수 있습니다.

   팁

   시험판 버전의 확장을 사용하면 쉽게 유지 관리하고 최종 사용자와 공유할 수 있는 형식인 Markdown 형식으로 API 설명서를 생성할 수 있습니다. 정의에서 마우스 오른쪽 단추를 클릭하고 Markdown 생성을 선택합니다.

HTTP 파일 생성

API 센터의 API 정의에 따라 .http 파일을 볼 수 있습니다. REST 클라이언트 확장이 설치된 경우 Visual Studio Code 편집기에서 요청 디렉터리를 만들 수 있습니다. 이 기능은 API 센터의 OpenAPI 기반 API에서만 사용 가능합니다.

1. API 센터 트리 뷰를 확장하여 API 정의를 표시합니다.

2. 정의를 마우스 오른쪽 단추로 클릭하고 HTTP 파일 생성을 선택합니다. API 사양으로 채워진 .http 문서를 렌더링하는 새 탭이 표시됩니다.

   

3. 요청을 보내려면 엔드포인트를 선택하고 요청 보내기를 선택합니다.

   참고 항목

   요청을 보내려면 API에 따라 권한 부여 자격 증명이나 API 키를 제공해야 할 수 있습니다.

API 클라이언트 생성

Microsoft Kiota 확장을 사용하여 선호하는 언어의 API 클라이언트를 생성합니다. 이 기능은 API 센터의 OpenAPI 기반 API에서만 사용 가능합니다.

1. API 센터 트리 뷰를 확장하여 API 정의를 표시합니다.
2. 정의를 마우스 오른쪽 단추로 클릭하고 API 클라이언트 생성을 선택합니다. Kiota OpenAPI 생성기 창이 나타납니다.
3. SDK에 포함하려는 API 엔드포인트와 HTTP 작업을 선택합니다.
4. API 클라이언트 생성을 선택합니다.

   1. SDK 이름, 네임스페이스 및 출력 디렉터리에 대한 구성 세부 정보를 입력합니다.

   2. 생성된 SDK의 언어를 선택합니다.

      

클라이언트가 생성됩니다.

Kiota 확장 사용 방법에 대한 자세한 내용은 Visual Studio Code용 Microsoft Kiota 확장을 참조하세요.

API 사양 내보내기

정의에서 API 사양을 내보낸 다음 파일로 다운로드할 수 있습니다.

확장의 트리 뷰에서 사양을 내보내려면 다음 안내를 따릅니다.

1. API 센터 트리 뷰를 확장하여 API 정의를 표시합니다.

2. 정의를 마우스 오른쪽 단추로 클릭하고 API 사양 문서 내보내기를 선택합니다. API 사양 문서를 렌더링하는 새 탭이 나타납니다.

   

명령 팔레트를 사용하여 사양을 내보낼 수도 있습니다.

1. 명령 팔레트를 열려면 Ctrl+Shift+P 바로 가기 키를 입력합니다.
2. Azure API 센터: API 사양 문서 내보내기를 선택합니다.
3. API 정의로 이동하려면 선택합니다. API 사양 문서를 렌더링하는 새 탭이 나타납니다.

관련 콘텐츠

• Azure API Center - 주요 개념
• Visual Studio Code에서 플랫폼 API 카탈로그 사용 및 보기