OpenAPI.NET Hidi

소개

OpenAPI.NET Hidi는 .NET 환경에서 OpenAPI 문서를 다루기 위한 객체 모델과 직렬화 도구를 제공하는 라이브러리입니다.

핵심 기능

• OpenAPI 2.0, 3.0.x, 3.1.x 스펙을 지원하는 객체 모델 제공
• OpenAPI 문서를 YAML 및 JSON 형식으로 직렬화·역직렬화 가능한 일반 직렬기 포함
• OpenAPI Workbench 라는 GUI 애플리케이션을 통해 파일 입력, 포맷 변환, 외부 참조 처리 기능 제공

지원 환경

.NET 기반 애플리케이션에서 사용 가능하며, Windows에서 winget을 통해 패키지 설치가 가능합니다.

기본 사용법

1. winget 또는 NuGet을 통해 Microsoft.OpenAPI.Hidi 패키지를 설치합니다.
2. 프로젝트에 using Microsoft.OpenAPI.Hidi; 를 추가합니다.
3. OpenAPI 문서(YAML 또는 JSON)를 로드하여 객체 모델로 변환합니다.
4. 필요에 따라 모델을 탐색하거나 JSON/YAML로 직렬화하여 저장합니다.
5. OpenAPI Workbench를 실행하여 입력 파일 선택, 포맷(YAML/JSON) 및 버전 선택 후 변환 결과를 확인할 수 있습니다.

제한 사항 및 체크포인트

• .NET 실행 환경이 필요하며, 순수하게 끝 사용자용 독립 실행형 프로그램이 아닙니다.
• 지원하는 OpenAPI 버전은 스크린샷에 표시된 V2.0, V3.0.4, V3.1.1 등이며, 그 외 버전은 보장되지 않습니다.
• 외부 참조 해결은 ‘Resolve External’ 옵션을 통해 가능하지만, 복잡한 참조 구조에 대한 자세한 동작은 문서를 참조해야 합니다.

자주 묻는 질문(FAQ)

• Q: 이 라이브러리는 어떤 파일 형식을 처리할 수 있나요?
  A: OpenAPI 사양의 YAML 및 JSON 형식을 읽고 쓸 수 있습니다.
• Q: 별도의 UI 없이 프로그래밍 방식으로만 사용할 수 있나요?
  A: 네, 객체 모델과 직렬기를 직접 호출하여 코드 내에서 OpenAPI 문서를 처리할 수 있습니다.
• Q: 설치는 어떻게 하나요?
  A: winget 명령어 또는 NuGet 패키지 관리자를 통해 Microsoft.OpenAPI.Hidi를 설치할 수 있습니다.

화면으로 보는 주요 기능

OpenAPI Workbench 화면

OpenAPI Workbench라는 애플리케이션의 사용자 인터페이스를 보여주며, 왼쪽에는 'Input File' 입력란과 'Input Content' 텍스트 영역이 있다. 'Input Content'에는 OpenAPI 3.0.1 스펙의 YAML 코드가 입력되어 있고, 오른쪽 상단에는 'Format' 옵션( YAML, JSON 선택 가능)과 'Version' 옵션( V3.1.1, V3.0.4, V2.0 선택 가능)이 있다. 'Convert' 버튼이 있으며, 'Inline Local', 'Resolve External', 'Inline External' 체크박스도 있다. 오른쪽 하단에는 'Parsing'과 'Rendering' 시간이 표시되며, 변환된 OpenAPI 3.1.1 스펙의 YAML 코드가 출력된다. 'Statistics' 영역에는 'Path Items: 1', 'Operations: 1', 'Parameters: 0', 'Request Bodies: 0' 등의 정보가 있다.