API 센터에서 API 분석 - Microsoft 관리

조직의 API 센터에 는 조직 스타일 규칙을 준수하기 위해 API 정의를 분석하는 Microsoft에서 관리하는 기본 제공 Linting 기능(미리 보기)이 포함되어 개별 보고서와 요약 보고서를 모두 생성합니다. API 분석은 API 정의의 일반적인 오류 및 불일치를 식별하고 수정하는 데 도움이 됩니다.

API 분석 사용:

• Azure API Center는 API 정의를 추가하거나 업데이트할 때마다 API 정의를 자동으로 분석합니다. API 정의는 기본적으로 spectral:oas 규칙 집합(API 스타일 가이드)을 사용하여 linted됩니다.
• API 분석 보고서는 API 정의가 스타일 가이드를 준수하는 방법을 보여 주는 Azure Portal에서 생성됩니다.
• Visual Studio Code용 Azure API 센터 확장을 사용하여 사용자 고유의 API 스타일 가이드를 로컬로 사용자 지정 및 테스트한 다음, API 센터에 배포할 수 있습니다.

제한 사항

• 현재 JSON 또는 YAML 형식의 OpenAPI 및 AsyncAPI 사양 문서만 분석됩니다.
• 현재는 단일 규칙 집합을 구성하며, 이는 API Center의 모든 OpenAPI 정의에 적용됩니다.
• 분석된 최대 API 정의 수에는 제한이 있습니다. 분석을 완료하는 데 몇 분에서 최대 24시간이 걸릴 수 있습니다.

필수 조건

• Azure 구독의 API 센터입니다. 아직 API 센터를 만들지 않았다면 빠른 시작: API 센터 만들기를 참조하세요.
• 규칙 집합, Visual Studio Code 및 다음 Visual Studio Code 확장을 사용자 지정하기 위해 다음을 수행합니다.
  • Visual Studio Code용 Azure API 센터 확장
  • Visual Studio Code용 Spectral 확장

API 분석 보고서 보기

Azure Portal에서 API 정의에 대한 분석 요약과 분석 보고서를 확인합니다. API 정의가 분석된 후, 구성된 API 스타일 가이드에 따라 오류, 경고 및 정보가 보고서에 나열됩니다.

API 분석 보고서에서는 분석에 사용된 규칙 집합과 린팅 패스 기록도 검토합니다.

API Center에서 분석 요약을 보려면:

1. 포털에서 API 센터로 이동합니다.

2. 왼쪽 메뉴의 거버넌스에서 API 분석을 선택합니다. 요약이 나타납니다.

   

3. 선택적으로 API 정의에 대한 API 분석 보고서 아이콘을 선택합니다. 다음 스크린샷에 표시된 대로, 정의의 API 분석 보고서가 나타납니다.

   

   팁

   API 정의 메뉴 막대에서 분석을 선택하여 API 분석 보고서를 볼 수도 있습니다.

규칙 집합 사용자 지정

Visual Studio Code용 Azure API Center 확장을 사용하여 API 센터의 기본 규칙 집합을 사용자 지정하거나 조직의 API 스타일 가이드로 바꿀 수 있습니다. 예를 들어, 규칙 집합을 확장하거나 사용자 지정 함수를 추가할 수 있습니다.

규칙 집합을 사용자 지정하거나 바꾸려면:

1. Visual Studio Code의 작업 막대에서 Azure API Center 아이콘을 선택합니다.
2. 작업 폴더의 .api-center-rules 루트에서 폴더를 엽니다.
3. API 센터 리소스의 폴더에서 파일을 엽니다 ruleset.yml .
4. 필요에 따라 콘텐츠를 수정하거나 바꿉니다.
5. 변경 내용을 ruleset.yml에 저장합니다.

로컬에서 규칙 집합 테스트

사용자 지정 규칙 집합을 API Center에 배포하기 전에 로컬에서 유효성을 검사합니다. Visual Studio Code용 Azure API Center 확장은 Spectral을 사용하여 API 사양 린팅에 대한 통합 지원을 제공합니다.

1. Visual Studio Code에서 Ctrl+Shift+P 바로 가기 키를 사용하여 명령 팔레트를 엽니다.

2. Azure API Center: 활성 API 스타일 가이드 설정을 입력하고 Enter 키를 누릅니다.

3. 로컬 파일 선택을 선택하고 사용자 지정한 ruleset.yml 파일을 지정합니다. Enter 키를 누릅니다.

   이 단계에서는 사용자 지정 규칙 집합을 린팅을 위한 활성 API 스타일 가이드로 만듭니다.

이제 OpenAPI 기반 API 정의 파일을 열면 Visual Studio Code에서 로컬 린팅 작업이 자동으로 트리거됩니다. 결과는 편집기와 문제 창(보기 > 문제 또는 Ctrl+Shift+M)에 직접 표시됩니다.

린팅 결과를 검토합니다. 규칙집합에 필요한 조정을 하고 원하는 대로 수행될 때까지 로컬에서 계속 테스트합니다.

API Center에 규칙 집합 배포

API Center에 사용자 지정 규칙 집합을 배포하려면:

1. Visual Studio Code의 작업 막대에서 Azure API Center 아이콘을 선택합니다.
2. API Center 창에서 규칙 집합을 사용자 지정한 API Center 리소스를 확장합니다.
3. 규칙을 마우스 오른쪽 단추로 클릭하고 API Center에 규칙 배포를 선택합니다.

규칙이 API Center에 성공적으로 배포되면 메시지가 표시됩니다. 린팅 엔진은 업데이트된 규칙 집합을 사용하여 API 정의를 분석합니다.

업데이트된 규칙 집합으로 린팅한 결과를 보려면 포털에서 API 분석 보고서를 확인합니다.

관련 콘텐츠

• 기본 제공 규칙 집합에 대한 자세한 내용은 Spectral GitHub 리포지토리를 참조하세요.
• API Center에서 API 분석 사용 - 자체 관리