OpenAPI Specification (OAS)란?
**OpenAPI Specification (OAS)**는 RESTful API의 인터페이스를 기술하기 위한 언어에 의존하지 않는 표준 사양입니다. 이전에는 ‘Swagger’로 불렸으나, 현재는 커뮤니티 주도의 오픈 프로젝트로서 관리되고 있습니다.
YAML 또는 JSON 형식으로 작성되며, 다음과 같은 개발 흐름의 자동화에 있어 없어서는 안 될 존재가 되었습니다.
- API 문서 자동 생성: Swagger UI 등을 통한 인터랙티브한 문서화.
- 클라이언트 코드 생성: 다양한 언어의 SDK(라이브러리) 자동 출력.
- 모의(Mock) 서버 구축: 프론트엔드 개발을 선행하기 위한 더미 서버 구축.
- 품질 관리: 요청 및 응답에 대한 스키마 검증.
스키마 정의 시 ‘중첩’의 과제
API 사양서를 작성할 때 가장 손이 많이 가는 작업은 요청 바디나 응답 바디의 ‘Schema’ 정의입니다.
특히 계층이 깊은(중첩된) 객체나 수많은 프로퍼티를 가진 JSON을 OpenAPI 구조(type, properties, required, items 등)에 맞춰 수동으로 작성하는 것은 시간이 많이 걸릴 뿐만 아니라 단순한 입력 실수의 원인이 되기도 합니다.
JSON을 통한 효율적인 자동 생성
이미 안정적으로 동작 중인 API가 있거나 샘플 응답 JSON 데이터가 있다면, 이를 바탕으로 스키마를 자동 생성하는 것이 가장 효율적입니다.
- 실제 API를 호출하여 JSON 데이터를 가져옵니다.
- JSON→OpenAPI 생성 도구에 해당 JSON을 붙여넣습니다.
- 단 몇 초 만에
components/schemas형식의 정의가 출력됩니다. - 생성된 정의를
openapi.yaml과 같은 여러분의 메인 정의 파일에 통합합니다.
DevToolKits 도구의 특징
저희 사이트의 생성 도구는 최신 OpenAPI 3.1.0 기준을 지원합니다.
- 타입 추론: 숫자, 문자열, 불리언, 객체, 배열을 정확하게 판별합니다.
- 필수 항목 추출: JSON에 포함된 프로퍼티를 자동으로
required항목으로 리스트업합니다(필요에 따라 나중에 조정 가능). - 타입 통합 (oneOf): 배열 내에 서로 다른 타입의 데이터가 혼재하는 경우,
oneOf를 사용하여 여러 타입을 포괄적으로 표현합니다. - 날짜 형식 감지:
2024-01-15T12:00:00Z와 같은 문자열을 감지하여format: date-time을 자동 부여합니다. - OpenAPI 3.1 준수:
nullable: true대신 최신 사양인type: "null"등의 표현에 최적화되어 있습니다.
💡 전문가의 팁: 자동 생성은 어디까지나 ‘초안’ 마련입니다. 생성 후 각 프로퍼티에
description이나example을 추가함으로써 팀원이나 API 사용자에게 친절하고 실용적인 문서로 완성해 보세요.