OpenAPI Specification (OAS)란 무엇인가요?
**OpenAPI Specification (OAS)**는 RESTful API 인터페이스를 설명하기 위한 언어 중립적인 표준 사양입니다. 이전에는 “Swagger”로 알려졌으나, 현재는 커뮤니티 주도 오픈 프로젝트로 관리되고 있습니다.
YAML 또는 JSON 형식으로 작성되는 OAS는 개발 수명 주기의 다양한 측면을 자동화하는 데 필수적인 도구가 되었습니다:
- 대화형 문서화: Swagger UI와 같은 도구를 통해 실시간 대화형 API 문서를 생성합니다.
- 코드 자동 생성: 수십 개의 언어로 클라이언트 SDK와 서버 스텁을 자동으로 생성합니다.
- 모의 서버(Mocking): 백엔드가 준비되기 전에 프론트엔드 개발을 진행할 수 있도록 가상 서버를 구축합니다.
- 유효성 검사: 요청 및 응답 데이터가 정의된 스키마를 준수하는지 확인합니다.
중첩된 스키마 정의의 어려움
API 명세서를 작성할 때 가장 번거로운 부분은 요청 및 응답 본문의 “스키마(Schema)” 정의입니다.
계층 구조가 깊은(중첩된) 객체나 속성이 많은 JSON을 OpenAPI 구조(type, properties, required, items 등)에 맞춰 수동으로 작성하는 것은 시간이 많이 걸릴 뿐만 아니라 사람의 실수가 발생하기 쉽습니다.
JSON을 통한 효율적인 자동 생성
이미 작동 중인 API가 있거나 샘플 응답 JSON 데이터가 있다면, 스키마를 자동으로 생성하는 것이 가장 효율적인 방법입니다.
- API를 실행하여 실제 JSON 응답을 얻습니다.
- 해당 JSON을 JSON → OpenAPI 변환 도구에 붙여넣습니다.
- 몇 초 만에
components/schemas정의가 생성됩니다. - 생성된 코드를
openapi.yaml또는openapi.json파일에 통합합니다.
DevToolKits 도구의 장점
DevToolKits의 생성 도구는 최신 OpenAPI 3.1.0 표준에 최적화되어 있습니다.
- 지능형 타입 유추: 정수, 숫자, 문자열, 불리언, 객체, 배열 등 타입을 정확하게 판별합니다.
- 필수 항목 자동 추출: JSON에 포함된 프로퍼티를 기반으로
required목록을 자동으로 생성합니다. - 혼합 배열 처리 (oneOf): 배열 안에 다양한 타입의 데이터가 섞여 있는 경우,
oneOf를 사용하여 각 잠재적 타입을 정의합니다. - 날짜 및 시간 감지:
2024-01-15T12:00:00Z와 같은 ISO 8601 문자열을 감지하여format: date-time을 자동으로 부여합니다. - OAS 3.1 최적화: 레거시인
nullable: true대신 최신 사양인type: "null"등을 적절하게 사용합니다.
💡 전문가의 팁: 자동 생성은 훌륭한 시작점입니다. 전문적인 문서를 위해서는 생성된 스키마에
description이나example필드를 추가하여 다른 개발자들이 이해하기 쉬운 실용적인 문서로 다듬는 것을 권장합니다.