API Document Validator

📋 API 형식 검증

개요

경로: 좌측 사이드바 > API 형식 검증

메뉴 타입: 그룹 메뉴 (하위 메뉴 포함)

API 형식 검증은 API 스펙의 형식과 구조를 검증하고, 검증 현황을 모니터링하는 기능을 제공합니다.

접근 방법

1. 좌측 사이드바에서 "API 형식 검증" 메뉴를 클릭하여 하위 메뉴를 확장합니다
2. 확장된 하위 메뉴에서 원하는 기능을 선택합니다

💡 참고: API 형식 검증은 그룹 메뉴이므로 클릭 시 하위 메뉴가 확장/축소됩니다.

하위 메뉴 구성

API 형식 검증 메뉴를 클릭하면 다음 하위 메뉴들이 표시됩니다:

1. API 형식 설정 - API 형식 검증 규칙 설정
2. API 형식 현황 대시보드 - 검증 현황 조회 및 모니터링

---

API 형식 설정

경로: 좌측 사이드바 > API 형식 검증 > API 형식 설정

기능 설명

API 형식 설정 페이지에서는 API Docs Validator를 위한 검증 룰셋을 관리하고 프로젝트와 매핑할 수 있습니다.

페이지 구성

주요 섹션

1. API Docs Validator 설정
   • 룰셋 관리
   • 프로젝트 매핑
2. 검증 룰셋 관리
   • 기존 룰셋 목록 및 관리
   • 새 룰셋 추가 버튼
3. 프로젝트 선택
   • 프로젝트 드롭다운으로 특정 프로젝트 선택 가능

주요 기능

• 검증 룰셋 관리: 검증에 사용할 룰셋을 생성, 수정, 삭제
• 새 룰셋 추가: 새로운 검증 룰셋을 생성
• 프로젝트 매핑: 검증 룰셋을 특정 프로젝트와 연결
• 기본 룰셋:
  • OWASP Top10: OWASP Top 10 보안 취약점 검증 룰셋
  • OAS(2.X, 3.X): OpenAPI Specification 검증 룰셋

사용 방법

1. 좌측 사이드바에서 "API 형식 검증" 메뉴를 클릭하여 하위 메뉴를 확장합니다
2. 하위 메뉴에서 **"API 형식 설정"**을 선택합니다
3. 프로젝트 드롭다운에서 작업할 프로젝트를 선택합니다 (선택사항)
4. 검증 룰셋 관리 섹션에서 기존 룰셋을 확인하거나 관리합니다
5. 새 룰셋 추가 버튼을 클릭하여 새로운 검증 룰셋을 생성합니다
6. 룰셋 설정 완료 후 저장합니다

룰셋 유형

• OWASP Top10: 웹 애플리케이션 보안 취약점 상위 10개 항목 검증
• OAS(2.X, 3.X): OpenAPI Specification 2.x 및 3.x 버전 검증

주의사항

• ⚠️ 룰셋 생성 및 수정 후 반드시 저장해야 적용됩니다
• ⚠️ 프로젝트 매핑은 특정 프로젝트에만 검증 규칙을 적용할 때 사용합니다

---

API 형식 현황 대시보드

경로: 좌측 사이드바 > API 형식 검증 > API 형식 현황 대시보드

기능 설명

API 형식 현황 대시보드는 API 형식 검증 실행 이력과 결과를 조회하고 모니터링할 수 있는 대시보드입니다.

페이지 구성

검증 이력 테이블

검증 실행 이력을 테이블 형태로 확인할 수 있습니다.

컬럼명	설명
요청자	검증을 요청한 사용자
프로젝트명	검증 대상 프로젝트
API명	검증 대상 API
상태	검증 상태 (통과/실패 등)
Error Count	발견된 오류 개수
Error 원인	검증 실패 원인
검증 일시	검증이 실행된 날짜/시간
액션	상세 조회, 재검증 등 추가 작업

주요 기능

• 검증 이력 조회: 과거 검증 실행 이력 확인
• 검증 상태 모니터링: 검증 통과/실패 상태 확인
• 오류 정보 확인: Error Count 및 Error 원인 확인
• 필터링: 프로젝트 드롭다운을 통한 필터링 (선택사항)

사용 방법

1. 좌측 사이드바에서 "API 형식 검증" 메뉴를 클릭하여 하위 메뉴를 확장합니다
2. 하위 메뉴에서 **"API 형식 현황 대시보드"**를 선택합니다
3. 검증 이력 테이블에서 검증 실행 이력을 확인합니다
4. 프로젝트 드롭다운에서 특정 프로젝트를 선택하여 필터링합니다 (선택사항)
5. 테이블의 액션 컬럼에서 상세 정보 조회나 추가 작업을 수행합니다

테이블 기능

• 페이징: 검증 이력이 많을 경우 페이지 단위로 조회
• 정렬: 각 컬럼 헤더 클릭으로 정렬 기준 변경 (가능한 경우)
• 상세 조회: 액션 컬럼의 버튼으로 상세 정보 확인

활용 팁

• 💡 프로젝트 필터: 특정 프로젝트의 검증 이력만 확인하려면 프로젝트 드롭다운을 활용하세요
• 💡 상태 확인: 상태 컬럼으로 검증 통과/실패 여부를 빠르게 확인할 수 있습니다
• 💡 오류 분석: Error Count와 Error 원인 컬럼으로 검증 실패 원인을 파악할 수 있습니다
• 💡 최신 정보: 최신 검증 현황을 확인하려면 페이지를 새로고침하세요

---

Swagger 문서 형식 검증

경로: 좌측 사이드바 > API 형식 검증 > API 형식 검증

기능 설명

Swagger 문서 형식 검증은 개발된 API의 Swagger/OpenAPI 정의를 입력하고, 설정된 검증 규칙에 따라 검증하여 문서의 유효성을 확인하는 기능입니다. 실제 업무에서 개발하고 생성된 Swagger 문서를 이 화면에서 검증하여 표준 준수 여부와 오류를 사전에 발견할 수 있습니다.

페이지 구성

1. 프로젝트 설정 섹션

• 검증할 프로젝트: 드롭다운에서 검증할 프로젝트를 선택합니다
  • 예: otel-prj
• 프로젝트를 선택하면 해당 프로젝트에 적용된 검증 규칙이 자동으로 로드됩니다

2. 적용된 검증 규칙 섹션

선택한 프로젝트에 적용된 검증 규칙 룰셋과 규칙 목록을 표시합니다:

• Ruleset명: 적용된 룰셋 이름 (예: MCP Swagger)
• 적용 규칙 목록:
  • mcp-operation-id-required: operationId 필수 검증
  • mcp-operation-id-style: operationId 스타일 검증
  • mcp-operation-summary-required: operation summary 필수 검증
  • mcp-json-request-body: JSON request body 검증
  • mcp-json-request-body-schema: JSON request body schema 검증
  • 기타 규칙들
• 규칙 개수: "외에 총 N개 규칙 적용됨" 형태로 표시

3. Swagger JSON 입력 섹션

• 입력 필드: 대규모 텍스트 영역에 Swagger/OpenAPI JSON을 입력합니다
  • 기본 안내 문구: "Swagger JSON을 입력하세요"
  • OpenAPI 3.0 형식의 Swagger 정의를 입력할 수 있습니다
• 샘플 로드 버튼: 입력 필드 우측 상단에 위치한 파란색 버튼
  • 클릭 시 샘플 Swagger 정의(Petstore 예제 등)가 입력 필드에 자동으로 로드됩니다
  • 샘플을 통해 입력 형식을 확인하고 테스트할 수 있습니다
• 검증 상태 표시: 입력 필드 하단에 JSON 유효성 검증 결과 표시
  • Valid JSON: JSON 형식이 유효한 경우 녹색 체크 표시
  • OpenAPI Spec: OpenAPI 스펙을 따르는 경우 녹색 체크 표시
• SWAGGER 검증 실행 버튼: 중앙 하단에 위치한 크고 파란색 버튼
  • 입력된 Swagger JSON에 대해 설정된 검증 규칙을 실행합니다
  • 클릭 시 검증이 시작되고 결과가 하단에 표시됩니다
• 결과 내보내기 버튼: 검증 실행 버튼 옆에 위치한 녹색 버튼
  • 검증 결과를 파일로 내보낼 수 있습니다

4. 검증 결과 섹션

검증 실행 후 하단에 검증 결과가 표시됩니다:

요약 정보 (상단 카드 형태):

• 오류 (ERROR): 빨간색 배경으로 표시되는 오류 개수
  • 예: 1 오류
• 경고 (WARNING): 주황색 배경으로 표시되는 경고 개수
  • 예: 0 경고
• 통과 (SUCCESS): 녹색 배경으로 표시되는 통과 개수
  • 예: 8 통과
• FAIL 총 N개 이슈: 빨간색 레이블로 전체 이슈 개수 표시
  • 예: FAIL 총 1개 이슈

상세 결과 테이블:

컬럼명	설명
심각도	ERROR (빨간색) 또는 SUCCESS (녹색)로 표시
규칙	적용된 검증 규칙 이름 (예: mcp-json-request-body)
메시지	검증 결과 메시지 (예: "content" property must have...)
경로	오류가 발생한 Swagger 정의 내의 경로
Ruleset명	해당 규칙이 속한 룰셋 이름
액션	상세보기 버튼으로 각 항목의 상세 정보 확인 가능

테이블 기능:

• 페이징: 검증 결과가 많을 경우 페이지 단위로 조회 (예: "Rows per page: 10")
• 정렬: 컬럼 헤더 클릭으로 정렬 가능
• 상세보기: 각 항목의 액션 컬럼에서 상세보기 버튼 클릭으로 상세 정보 확인

주요 기능

1. 프로젝트별 검증 규칙 적용

• 프로젝트를 선택하면 해당 프로젝트에 매핑된 검증 규칙이 자동으로 적용됩니다
• 각 프로젝트마다 다른 검증 규칙을 적용할 수 있습니다

2. Swagger JSON 입력 및 검증

• 개발된 API의 Swagger/OpenAPI 정의를 직접 입력하여 검증할 수 있습니다
• JSON 형식 유효성과 OpenAPI 스펙 준수 여부를 실시간으로 확인할 수 있습니다

3. 샘플 로드 기능

• 샘플 로드 버튼을 클릭하면 샘플 Swagger 정의가 자동으로 입력됩니다
• 샘플을 통해 입력 형식을 확인하고 기능을 테스트할 수 있습니다

4. 검증 실행 및 결과 확인

• SWAGGER 검증 실행 버튼을 클릭하면 설정된 모든 검증 규칙이 실행됩니다
• 검증 결과는 오류, 경고, 통과로 분류되어 표시됩니다
• 각 검증 항목의 상세 정보(규칙, 메시지, 경로)를 확인할 수 있습니다

5. 결과 내보내기

• 검증 결과를 파일로 내보내어 문서화하거나 공유할 수 있습니다

사용 방법

기본 검증 프로세스

1. 프로젝트 선택: 상단의 검증할 프로젝트 드롭다운에서 검증할 프로젝트를 선택합니다
2. 검증 규칙 확인: 적용된 검증 규칙 섹션에서 적용될 규칙 목록을 확인합니다
3. Swagger JSON 입력:
   • 방법 1: 개발된 API의 Swagger JSON을 복사하여 입력 필드에 붙여넣습니다
   • 방법 2: 샘플 로드 버튼을 클릭하여 샘플 Swagger를 로드하고 수정합니다
4. JSON 유효성 확인: 입력 필드 하단의 Valid JSON과 OpenAPI Spec 체크 표시를 확인합니다
5. 검증 실행: SWAGGER 검증 실행 버튼을 클릭합니다
6. 결과 확인: 하단의 검증 결과 섹션에서 요약 정보와 상세 결과를 확인합니다
7. 오류 수정: 오류가 발견된 경우 메시지와 경로를 참고하여 Swagger 정의를 수정합니다
8. 재검증: 수정 후 다시 검증을 실행하여 모든 오류가 해결되었는지 확인합니다

실제 업무 활용 시나리오

시나리오 1: 개발 완료 후 Swagger 검증

1. API 개발을 완료하고 Swagger/OpenAPI 정의를 생성합니다
2. 좌측 사이드바에서 API 관리 > API 형식 검증 메뉴로 이동합니다
3. 검증할 프로젝트에서 해당 프로젝트를 선택합니다
4. 생성된 Swagger JSON을 복사하여 입력 필드에 붙여넣습니다
5. SWAGGER 검증 실행 버튼을 클릭합니다
6. 검증 결과를 확인하고 오류가 있으면 수정합니다
7. 모든 검증을 통과할 때까지 반복합니다

시나리오 2: 샘플을 활용한 검증 테스트

1. 검증할 프로젝트를 선택합니다
2. 샘플 로드 버튼을 클릭하여 샘플 Swagger를 로드합니다
3. 샘플 Swagger를 참고하여 실제 Swagger 정의를 작성합니다
4. SWAGGER 검증 실행 버튼을 클릭하여 검증합니다
5. 검증 결과를 확인하고 필요한 수정을 진행합니다

시나리오 3: 검증 규칙 준수 확인

1. 프로젝트를 선택하여 적용된 검증 규칙을 확인합니다
2. Swagger JSON을 입력합니다
3. 검증을 실행합니다
4. 상세 결과 테이블에서 각 규칙별 검증 결과를 확인합니다
5. ERROR 또는 WARNING이 있는 규칙을 확인하고 해당 부분을 수정합니다
6. 상세보기 버튼을 클릭하여 오류의 상세 정보를 확인합니다

활용 예시

예시 1: 기본 검증 실행

1. 프로젝트 otel-prj 선택
2. 샘플 로드 버튼 클릭하여 샘플 Swagger 로드
3. SWAGGER 검증 실행 버튼 클릭
4. 검증 결과 확인:
   • 오류: 1개
   • 경고: 0개
   • 통과: 8개

예시 2: 실제 Swagger 검증

1. 개발 완료된 API의 Swagger JSON 복사
2. 프로젝트 선택 (예: otel-prj)
3. Swagger JSON을 입력 필드에 붙여넣기
4. JSON 유효성 확인 (Valid JSON, OpenAPI Spec 체크)
5. SWAGGER 검증 실행 버튼 클릭
6. 검증 결과에서 오류 확인:
   • 예: mcp-json-request-body 규칙 위반
   • 메시지: "content" property must have required property "application/json"
   • 경로: paths./pet/{petId}/uploadImage.post.requestBody.content
7. Swagger 정의에서 해당 경로의 오류 수정
8. 수정 후 재검증 실행
9. 모든 검증 통과 확인

예시 3: 검증 결과 분석

1. 검증 실행 후 검증 결과 섹션 확인
2. 요약 정보에서 전체 이슈 개수 확인 (예: FAIL 총 1개 이슈)
3. 상세 결과 테이블에서 각 항목 확인:
   • 심각도: ERROR인 항목 우선 확인
   • 규칙: 어떤 규칙에서 실패했는지 확인
   • 메시지: 구체적인 오류 내용 확인
   • 경로: Swagger 정의에서 수정해야 할 위치 확인
4. 상세보기 버튼 클릭하여 추가 정보 확인
5. 오류 수정 후 재검증

주의사항

• ⚠️ 프로젝트 선택 필수: 검증 규칙은 프로젝트별로 다를 수 있으므로 반드시 올바른 프로젝트를 선택해야 합니다
• ⚠️ JSON 형식 준수: 입력한 Swagger는 유효한 JSON 형식이어야 하며, OpenAPI 스펙을 따라야 합니다
• ⚠️ 검증 규칙 확인: 프로젝트에 적용된 검증 규칙을 미리 확인하여 필요한 항목을 준수하도록 Swagger를 작성하세요
• ⚠️ 오류 수정 후 재검증: 오류를 수정한 후에는 반드시 재검증을 실행하여 모든 오류가 해결되었는지 확인하세요
• ⚠️ 검증 결과 저장: 중요한 검증 결과는 결과 내보내기 기능을 활용하여 저장하세요

활용 팁

• 💡 샘플 활용: 처음 사용하는 경우 샘플 로드 버튼을 활용하여 입력 형식을 확인하세요
• 💡 실시간 검증: JSON을 입력하는 동안 Valid JSON과 OpenAPI Spec 표시를 확인하여 실시간으로 형식을 검증할 수 있습니다
• 💡 규칙별 확인: 검증 결과 테이블에서 규칙별로 필터링하여 특정 규칙의 검증 결과만 확인할 수 있습니다
• 💡 경로 활용: 검증 결과의 경로 정보를 활용하여 Swagger 정의에서 정확한 위치를 찾아 수정할 수 있습니다
• 💡 반복 검증: 개발 중간중간 검증을 실행하여 오류를 조기에 발견하고 수정하는 것이 효율적입니다