API 인사이트에서 API 사양 확인 중

  • 릴리스 버전: Australia
  • 업데이트 날짜 2026년 03월 12일
  • 소요 시간: 4분

    • API 사양 유효성 검사 규칙에 액세스하여 API 사양이 완전하고 일관되며 베스트 프랙티스를 준수하는지 확인할 수 있습니다.

    검증 규칙은 임포트 또는 분석 중에 구조적 문제를 조기에 식별하여 전반적인 API 품질을 개선합니다. 이러한 규칙을 관리하여 API 사양 전반에 걸쳐 표준화를 적용하고 API가 프로덕션에 게시되거나 사용되기 전에 누락되거나 잘못된 필드를 확인하여 오류를 줄일 수 있습니다.

    API 사양 저장

    API 사양 [sn_api_insights_ws_api_specification] 테이블에는 개별 API를 설명하는 사양 문서가 저장됩니다. 각 기록에는 사양이 속한 API를 식별하고 여러 버전을 관리하기 위한 다음 세부 정보가 포함됩니다.
    표 1. API 사양 상세 정보
    필드 설명
    이름 API의 이름입니다.
    버전 API의 버전입니다.
    유형 사용 중인 API 사양 표준의 형식 및 버전입니다. 예를 들어 OpenAPI 사양의 경우 openapi3.0.0 입니다.
    상태 API 사양이 해당 규칙 및 확인 결과에 대해 확인되었는지 여부를 나타내는 현재 상태입니다. 유효한 값은 다음과 같습니다.
    • 처리되지 않음: API 사양의 유효성이 검사되지 않았음을 나타냅니다.
    • 유효: API 사양이 성공적으로 확인 및 처리되었는지 또는 경고가 발생했음을 나타냅니다. 경고가 있으면 메시지 필드에 상세 정보가 표시됩니다.
    • 잘못됨: API 사양이 확인되었지만 오류가 있음을 나타냅니다. 오류 상세 정보가 메시지 필드에 표시됩니다.
    사양 API 사양 파일의 전체 내용입니다.
    주:
    OpenAPI의 경우 엔드포인트, 메서드 및 스키마를 설명하는 전체 OpenAPI 문서가 포함되어 있습니다.
    메시지 메시지는 사양 유형에 대한 모든 유효성 검사 규칙을 처리한 후에 생성됩니다. 여기에는 설명과 함께 오류 또는 경고가 포함됩니다.

    유효성 검사 규칙 구조

    사양 확인 규칙 [sn_api_insights_ws_spec_validation_rule] 테이블에는 API 사양 [sn_api_insights_ws_api_specification] 테이블에 정의된 API 사양에 대한 확인 규칙이 저장됩니다.
    주:
    유효성 검사 규칙을 편집하거나 삭제하려면 sn_cmdb_editor 역할이 필요하고, 규칙을 보려면 cmdb_read 역할이 필요합니다.

    각 유효성 검사 규칙에는 다음과 같은 핵심 구성요소가 포함되어 있습니다.

    표 2. 유효성 확인 규칙 구성요소
    구성요소 설명
    사양 규칙이 설계된 API 사양입니다.
    버전 규칙이 확인하는 API 사양의 버전입니다. 지정된 경우 규칙은 해당 버전에만 적용됩니다. 확인을 특정 버전으로 제한하려면 버전 필드에서 해당 버전을 지정합니다. 여러 값을 쉼표로 구분합니다. 예: 1.0,1.1,2.0
    주:
    버전 필드를 비워 두면 지정된 API 사양 유형의 설치된 모든 버전에 대해 규칙이 실행됩니다.
    유형 수행할 확인 유형입니다. 유효한 값은 다음과 같습니다.
    • 경로: API 사양 문서의 지정된 섹션에서 특정 키가 객체 배열, 개별 객체 또는 둘 다 내에 있는지 확인합니다.
    • 예상 값: 지정된 키가 값 필드에 지정된 예상 값과 일치하는지 여부를 확인합니다. 이 유효성 검사는 키 필드에 지정된 단일 키에만 적용됩니다.
    키 확인할 사양의 일부입니다. 예상 값이 제공되지 않은 경우 키 필드에 여러 키를 쉼표로 구분하여 입력할 수 있습니다.
    값 키 필드에 지정된 키의 예상 값입니다. 여러 값을 쉼표로 구분합니다.
    심각도 확인 규칙 결과의 심각도 수준(경고 또는 오류)입니다.
    주:
    경고로 설정하면 규칙이 충족되지 않으면 API 사양이 유효하게 유지되어 실패가 아님을 나타내고 메시지만 표시됩니다.
    메시지 규칙이 트리거될 때 문제에 대한 설명입니다.
    활성 규칙을 활성화하는 옵션입니다. 예약된 작업에서는 API Specification Validation 활성 규칙만 트리거됩니다.

    API 사양 확인 프로세스

    API Specification Validation 예약된 작업은 필요한 표준을 준수하는지 확인하기 위해 사양 유형을 기준으로 활성 규칙에 대해 처리되지 않은 API 사양을 자동으로 검증합니다.

    확인 프로세스에는 다음이 포함됩니다.
    1. 사양 확인 규칙 [sn_api_insights_ws_spec_validation_rule] 테이블에서 모든 활성 확인 규칙을 검색합니다.
    2. API 사양 [sn_api_insights_ws_api_specification] 테이블에서 처리되지 않음으로 표시된 API를 선택합니다.
    3. OpenAPI와 같은 사양 유형에 따라 선택한 각 API에 관련 유효성 검사 규칙을 적용합니다.
    4. API 사양 내에서 특정 필드 또는 해당 값의 존재 여부 또는 정확성 확인.
    5. 처리 상태를 업데이트하고 오류 또는 경고를 캡처합니다.

    OpenAPI 사양에 대해 미리 정의된 규칙

    기본적으로 애플리케이션에는 OpenAPI 사양에 대한 다음 유효성 검사 규칙이 포함되어 있습니다.
    태그 확인
    API 사양의 각 태그에 이름 필드가 포함되어 있는지 확인합니다. 이름 필드가 없으면 시스템은 경고 메시지를 반환하지만 사양은 유효한 것으로 표시합니다.
    필수 섹션 확인
    API 사양에 필요한 최상위 섹션( 정보, 경로 및 구성요소)이 포함되어 있는지 확인합니다. 이러한 섹션 중 하나라도 누락된 경우 시스템은 오류 메시지를 반환하고 사양을 잘못됨으로 표시합니다.
    서버 확인 섹션
    API 사양에 서버 엔드포인트를 정의하는 서버 섹션이 포함되어 있는지 확인합니다. 서버 섹션이 누락되면 시스템은 오류 메시지를 반환하고 사양을 잘못된 것으로 표시합니다.

    이러한 미리 정의된 규칙은 OpenAPI 사양의 태그 지정, 메타데이터 및 서버 정의와 같은 중요한 섹션을 확인합니다.