본문으로 건너뛰기
버전: Latest(v3.0) 🔥

API Docs Validator

API 문서 검증​

개요​

Path: 왼쪽 사이드바 → API Document Validation 

Menu Type: 그룹 메뉴 (하위 메뉴 포함) 

API 문서 검증 기능은 API 사양의 형식과 구조를 검증하고 검증 상태를 모니터링하는 기능을 제공합니다. 

접근 방법​

  1. 왼쪽 사이드바에서 API Document Validation 메뉴를 클릭하여 하위 메뉴를 확장합니다.
  2. 확장된 하위 메뉴 목록에서 원하는 기능을 선택합니다.

💡 참고: API 문서 검증은 그룹 메뉴이므로 클릭하면 하위 메뉴의 확장 및 축소가 전환됩니다.

사용자가 API 문서 검증 메뉴를 클릭하면 다음 하위 메뉴가 표시됩니다: 

  1. API Document Settings – API 검증 규칙 구성
  2. API Document Status Dashboard – 검증 상태 보기 및 모니터링

API 문서 설정​

Path : Left Sidebar > API Document Validation > API Document Settings

기능 개요​

API 문서 설정 페이지는 사용자가 API Docs Validator를 위한 검증 규칙 세트를 정의, 관리 및 적용할 수 있도록 합니다. 사용자가 사용자 정의 가능한 규칙 세트를 생성하고, 검증 기능을 구성하며, 이를 특정 프로젝트에 매핑할 수 있도록 하여 표준화된 API 문서 품질을 지원합니다.

페이지 구조​

Main Section
  1. API Docs Validator Setting
    • 규칙 세트 관리
    • 프로젝트 매핑
  2. Validation Ruleset Management
    • 기존 규칙 세트 목록 보기 및 관리
  • Add New Ruleset 버튼
  1. Project Selection
    • 프로젝트 드롭다운을 사용하여 특정 프로젝트 선택

주요 기능​

  • Validation Ruleset Management: 유효성 검사 규칙 세트를 생성, 편집 및 삭제
  • Add New Ruleset: 미리 정의된 템플릿을 사용하여 새로운 규칙 세트를 생성하고 유효성 검사 기능을 추가하거나 제거하여 사용자 정의
  • Project Mapping: 특정 프로젝트와 유효성 검사 규칙 세트 연결
  • Default Rulesets
    • OWASP Top10: OWASP Top 10 보안 취약점을 기반으로 한 유효성 검사 규칙
    • OAS(2.X, 3.X): OpenAPI 사양에 대한 유효성 검사 규칙

사용 방법​

  1. 왼쪽 사이드바에서 API Document Validation 메뉴를 클릭하여 하위 메뉴 확장
  2. 하위 메뉴에서 API Document Settings 선택
  3. Project 드롭다운에서 프로젝트 선택 (선택 사항)
  4. Validation Ruleset Management 섹션에서 기존 규칙 세트를 검토하거나 관리
  5. Add New Ruleset를 클릭하여 새로운 유효성 검사 규칙 세트 생성
    • Add New Ruleset을 클릭하면 세 가지 템플릿이 있는 모달 대화 상자가 나타납니다:
      • Default Rule
      • Basic Rule
      • Advanced Rule
    • 규칙 세트 정보 입력: 규칙 세트 이름, 설명 입력
    • 템플릿을 선택하고 유효성 검사 기능을 사용자 정의:
      • Functions List을 열어 템플릿에 포함된 모든 유효성 검사 기능 보기
      • 편집기에서 기존 기능을 삭제하여 제거하고, 사용 가능한 기능 목록에서 새로운 기능을 추가하려면 기능을 클릭
      • 기능 이름 위에 마우스를 올려 짧은 설명 보기
      • 기능 목록 아래의 링크를 클릭하여 새 탭에서 열기
  6. 규칙 세트 관리 목록에 새 항목을 추가하려면 Save 버튼 클릭.

규칙 세트 유형​

  • OWASP Top10: 상위 10개 웹 애플리케이션 보안 취약성을 검증합니다.
  • OAS(2.X, 3.X): Validates OpenAPI Specification versions 2.x and 3.x

주의사항​

  • ⚠️ 규칙 세트의 변경 사항은 적용되기 위해 저장해야 합니다.
  • ⚠️ 검증 규칙이 특정 프로젝트에만 적용될 때는 프로젝트 매핑을 사용해야 합니다.

API 문서 상태 대시보드​

기능 설명​

API 문서 상태 대시보드는 사용자가 API 형식 검증 실행 이력 및 결과를 보고 모니터링할 수 있도록 합니다.

페이지 구조​

Validation History Table

검증 실행 이력을 표 형식으로 표시합니다.

열 이름설명
요청자검증을 요청한 사용자
프로젝트 이름대상 프로젝트
API 이름대상 API
상태검증 상태 (통과 / 실패 등)
오류 수감지된 오류의 수
오류 원인검증 실패의 이유
검증 시간실행 날짜 및 시간
작업세부정보 보기, 검증 다시 실행 등

주요 기능​

  • View Validation History: 과거 검증 실행 검토
  • Monitor Validation Status: 통과/실패 결과 확인
  • Error Analysis: 오류 수 및 원인 검토
  • Filtering: 프로젝트 드롭다운을 사용하여 프로젝트별로 필터링 (선택 사항)

사용 방법​

  1. 왼쪽 사이드바에서 API Document Validation 메뉴를 클릭하여 하위 메뉴를 확장합니다.
  2. 하위 메뉴에서 API Document Settings 을 선택합니다.
  3. Validation History 표에서 검증 실행 이력을 확인합니다.
  4. Project 드롭다운을 사용하여 필터링할 특정 프로젝트를 선택합니다 (선택 사항).
  5. 테이블의 Actions 열을 사용하여 세부정보를 보거나 추가 작업을 수행하세요.

테이블 기능​

  • Pagination: 기록이 큰 경우 결과를 페이지별로 보기
  • Sorting: 열 머리글을 클릭하여 정렬하기 (지원되는 경우)
  • Detail View: 작업 열을 통해 자세한 정보 보기

사용 팁​

  • 💡 Project Filtering: 특정 프로젝트에 대한 검증 기록을 보려면 프로젝트 드롭다운을 사용하세요.
  • 💡 Status Check: 상태 열을 통해 합격/불합격 결과를 빠르게 식별하세요.
  • 💡 Error Analysis: Error Count 및 Error Cause 열을 사용하여 검증 문제를 식별하세요.
  • 💡 Latest Data: 페이지를 새로 고쳐 가장 최근의 검증 결과를 확인하세요.

Swagger 문서 형식 검증​

기능 개요​

Swagger 문서 형식 검증은 사용자가 Swagger/OpenAPI 정의를 입력하고 구성된 규칙에 따라 검증할 수 있도록 합니다. 이는 배포 전에 Swagger 문서의 표준 준수 문제와 오류를 식별하는 데 도움이 됩니다.

페이지 구조​

1. Project Configuration Section
  • Project Selection: 검증할 프로젝트 선택
    • 예: otel-prj
  • 선택한 프로젝트에 따라 적용된 검증 규칙이 자동으로 로드됩니다.
2. Applied Validation Rules Section

선택한 프로젝트에 적용된 규칙 세트와 규칙을 표시합니다:

  • Ruleset Name: 적용된 규칙 세트의 이름 (예: MCP Swagger)
  • Applied Rules Examples:
    • mcp-operation-id-required: operationId 검증 필요
    • mcp-operation-id-style: operationId 스타일 검증
  • mcp-operation-summary-required: operation summary validation required
    • mcp-json-request-body: JSON request body validation
    • mcp-json-request-body-schema: JSON request body schema validation
    • Other rules
  • Rule count: 총 규칙 수를 표시합니다 (예: “그리고 N개의 추가 규칙이 적용됨”)
3. Swagger JSON Input Section
  • Input Field: 사용자가 Swagger/OpenAPI JSON 정의를 입력할 수 있는 큰 텍스트 영역입니다.
    • 기본 안내 메시지: "Swagger JSON을 입력하세요"
    • OpenAPI 3.0 형식의 Swagger 정의를 지원합니다.
  • Load Sample Button: 입력 필드의 오른쪽 상단에 위치한 파란색 버튼입니다.
    • 샘플 Swagger 정의(예: Petstore 예제)를 입력 필드에 자동으로 로드합니다.
    • 사용자가 입력 형식을 검토하고 테스트 유효성 검사를 수행할 수 있도록 합니다.
  • Validation Status Indicators: 입력 필드 아래에 JSON 유효성 검사 결과를 표시합니다.
    • 유효한 JSON: JSON 형식이 유효할 때 녹색 체크 아이콘으로 표시됩니다.
    • OpenAPI 사양: 정의가 OpenAPI 사양을 준수할 때 녹색 체크 아이콘으로 표시됩니다.
  • Run Swagger Validation Button: 페이지 하단 중앙에 위치한 큰 파란색 버튼입니다.
    • 입력된 Swagger JSON에 대해 구성된 모든 유효성 검사 규칙을 실행합니다.
    • 클릭 즉시 유효성 검사가 시작되며 결과가 아래에 표시됩니다.
  • Export Results Button: 유효성 검사 실행 버튼 옆에 위치한 녹색 버튼입니다.
    • 사용자가 유효성 검사 결과를 파일로 내보낼 수 있도록 합니다.
4. Validation Results Section

유효성 검사가 실행된 후 결과가 페이지 하단에 표시됩니다.

Summary Information (상단 카드 형식):

  • ERROR: 감지된 오류 수, 빨간색 배경에 표시됩니다.
    • 예: 1 오류
  • WARNING: 감지된 경고 수, 주황색 배경에 표시됩니다.
    • 예: 0 경고
  • SUCCESS: 성공적인 검증의 수, 녹색 배경에 표시됨
    • 예: 8 성공
  • FAIL - Total N Issues: 검증 문제의 총 수, 빨간 레이블로 표시됨
    • 예: 실패 - 총 1 문제
Detailed Results Table:
열 이름설명
심각도오류(빨간색) 또는 성공(녹색) 표시
규칙적용된 검증 규칙 이름 (예: mcp-json-request-body)
메시지검증 결과 메시지 (예: "content" 속성은 ...이 있어야 함)
경로오류가 발생한 Swagger 정의 내의 경로
규칙 집합 이름규칙이 속한 규칙 집합의 이름
작업“View Detail” 버튼을 클릭하여 각 항목에 대한 자세한 정보를 보기
Table function:
  • Pagination: 대량의 검증 결과가 존재할 때 페이지별로 결과를 표시 (예: “페이지당 행: 10”)
  • Sorting: 열 헤더를 클릭하여 결과 정렬
  • Detail View:  Action 열의 View Details 버튼을 클릭하여 각 검증 항목에 대한 자세한 정보를 보기

주요 기능​

1. Apply Project-specific validation rules
  • 프로젝트가 선택되면 해당 프로젝트에 매핑된 검증 규칙이 자동으로 적용됩니다.
  • 각 프로젝트에 대해 서로 다른 검증 규칙을 적용할 수 있습니다.
2. Swagger JSON input and validation
  • 개발된 API의 Swagger/OpenAPI 정의를 직접 입력하여 검증할 수 있습니다.
  • JSON 형식 유효성 및 OpenAPI 사양 준수를 실시간으로 확인합니다.
3. Sample load function
  • Sample Load 버튼을 클릭하면 샘플 Swagger 정의가 자동으로 입력됩니다.
  • 샘플은 필수 입력 형식을 확인하고 기능을 테스트하는 데 사용할 수 있습니다.
4. Run validation and view results
  • Run Swagger Validation 버튼을 클릭하여 구성된 모든 검증 규칙을 실행합니다.
  • 검증 결과는 오류, 경고 또는 통과로 분류됩니다.
  • 각 검증 항목(규칙, 메시지, 경로)에 대한 자세한 정보를 볼 수 있습니다.
5. Export results
  • 검증 결과는 문서화 또는 공유를 위해 파일로 내보낼 수 있습니다.

사용 방법​

Basic Validation Process
  1. Select Project: 상단의 project to be validated 드롭다운에서 검증할 프로젝트를 선택합니다.
  2. Check Validation Rules: Applied Validation Rules 섹션에서 규칙 목록을 확인합니다.
  3. Enter Swagger JSON:
    • Method 1: 개발된 API의 Swagger JSON을 복사하여 입력 필드에 붙여넣습니다.
    • Method 2: Load Sample 버튼을 클릭하여 샘플 Swagger를 로드하고 수정합니다.
  4. Check JSON Validity: 입력 필드 하단에서 유효한 JSON 및 OpenAPI 사양에 대한 지표를 확인합니다.
  5. Run Validation: Run Swagger Validation 버튼을 클릭합니다.
  6. Review Results: 하단의 Validation Results 섹션에서 요약 정보와 자세한 결과를 모두 확인합니다.
  7. Fix Errors: 오류가 발견되면 메시지와 경로 정보를 참조하여 Swagger 정의를 수정합니다.
  8. Re-validate: 수정 후, 모든 오류가 해결되었는지 확인하기 위해 검증을 다시 실행합니다.

실제 사용 시나리오​

Scenario 1: Swagger Validation After Development Completion
  1. API 개발을 완료한 후 Swagger/OpenAPI 정의를 생성합니다.
  2. 왼쪽 사이드바에서 API Management > API Format Validation 로 이동합니다.
  3. project to be validated 섹션에서 검증할 프로젝트를 선택합니다.
  4. 생성된 Swagger JSON을 복사하여 입력 필드에 붙여넣습니다.
  5. Run Swagger Validation 버튼을 클릭합니다.
  6. 결과를 검토하고 오류를 수정합니다.
  7. 모든 검증이 통과할 때까지 반복합니다.

Scenario 2: Validation Test Using Sample  

  1. project to be validated를 선택합니다.
  2. Load Sample 버튼을 클릭하여 샘플 Swagger를 로드합니다.
  3. 샘플 Swagger를 참조하여 실제 Swagger 정의를 작성합니다.
  4. Run Swagger Validation 버튼을 클릭하여 유효성을 검사합니다.
  5. 결과를 검토하고 필요한 수정을 합니다.

Scenario 3: Validation Rule Compliance Check  

  1. 적용된 유효성 검사 규칙을 확인할 프로젝트를 선택합니다.
  2. Swagger JSON을 입력합니다.
  3. 유효성 검사를 실행합니다.
  4.  Detailed results table에서 각 규칙에 대한 유효성 검사 결과를 확인합니다.
  5. ERROR 및 WARNING이 있는 규칙을 검토하고 수정합니다.
  6. 오류에 대한 추가 정보를 보려면 View Details 버튼을 클릭합니다.

사용 예제​

Example 1: Basic Validation Execution 

  1. otel-prj 프로젝트를 선택합니다.
  2. Load Sample 을 클릭하여 샘플 Swagger를 로드합니다.
  3. Run Swagger Validation 을 클릭합니다.
  4. 유효성 검사 결과를 확인합니다:
    • 오류: 1
    • 경고: 0
    • 통과: 8

Example 2: Actual Swagger Validation 

  1. 완료된 API의 Swagger JSON을 복사합니다.
  2. 프로젝트를 선택합니다 (예: otel-prj).
  3. 입력 필드에 Swagger JSON을 붙여넣습니다.
  4. JSON 유효성을 확인합니다 (유효한 JSON, OpenAPI 사양 확인).
  5. Run Swagger Validation 버튼을 클릭합니다.
  6. 유효성 검사 결과에서 오류를 검토합니다:
    • 예: mcp-json-request-body 규칙 위반
    • 메시지: "content" 속성은 필수 속성 "application/json"을 가져야 합니다.
    • 경로: paths./pet/{petId}/uploadImage.post.requestBody.content
  7. Swagger 정의에서 이 경로의 오류를 수정합니다.
  8. 수정 후 유효성 검사를 다시 실행합니다.
  9. 모든 유효성 검사가 통과했는지 확인합니다.

Example 3: Validation Result Analysis 

  1. 유효성 검사를 실행한 후 Validation Results 섹션을 확인합니다.
  2. summary information에서 문제의 총 수를 확인합니다 (예: FAIL - 총 1개 문제).
  3. Detailed results table에서 각 항목을 확인합니다: 
    • Severity: ERROR가 있는 항목의 우선 순위를 확인합니다.
    • Rule: 어떤 규칙이 실패했는지 확인합니다.
  • Message: 특정 오류 세부정보 확인
    • Path: 수정해야 할 Swagger 정의의 정확한 위치 확인
  1. 추가 정보를 보려면 View Details를 클릭하세요.
  2. 오류를 수정하고 유효성 검사를 다시 실행하세요.

주의사항​

  • ⚠️ Project Selection Required: 각 프로젝트마다 유효성 검사 규칙이 다를 수 있으므로 올바른 프로젝트를 선택해야 합니다.
  • ⚠️ JSON Format Compliance: 입력된 Swagger는 유효한 JSON 형식이어야 하며 OpenAPI 사양을 준수해야 합니다.
  • ⚠️ Validation Rule Review: 프로젝트에 적용된 유효성 검사 규칙을 미리 확인하고 Swagger가 모든 필수 항목을 올바르게 따르도록 준비하세요.
  • ⚠️ Re-validation After Fixing: 오류를 수정한 후에는 모든 문제가 해결되었는지 확인하기 위해 유효성 검사를 다시 실행해야 합니다.
  • ⚠️ Save Validation Results: 중요한 유효성 검사 결과를 저장하려면 result 내보내기 기능을 사용하세요.

사용 팁​

  • 💡 Use Samples: 처음 사용할 때는 load sample 버튼을 사용하여 필요한 입력 형식을 확인하세요.
  • 💡 Real-time Validation: JSON을 입력하는 동안 실시간 유효성 검사를 위해 유효한 JSON 및 OpenAPI 사양 지표를 확인하세요.
  • 💡 Rule-based Filtering: 유효성 검사 결과 테이블은 규칙별로 필터링하여 특정 유효성 검사 규칙에 대한 결과만 볼 수 있습니다.
  • 💡 Path Utilization: 유효성 검사 결과의 경로 정보는 Swagger 정의에서 정확한 위치를 찾고 수정하는 데 사용할 수 있습니다.
  • 💡 Repeated validation: 개발 중에 주기적으로 유효성 검사를 실행하는 것은 오류를 조기에 발견하고 해결하는 데 효과적입니다.