OpenAPI YAML과 JSON 문서의 차이
OpenAPI 스펙을 정의할 때, YAML과 JSON 두 가지 포맷을 사용할 수 있습니다. YAML은 읽기 쉽고 인간이 이해하기 편한 구조를 가지고 있으며, JSON은 웹에서 널리 사용되며, JavaScript와의 호환성이 매우 높습니다. 다음은 이들 포맷의 주요 차이점입니다.
- 가독성: YAML은 보다 가독성이 높고, 주석을 추가하기 용이합니다. JSON은 데이터 전송에 최적화되어 있어, 기계가 처리하기에는 좋지만 인간이 읽기에는 YAML보다 다소 불편할 수 있습니다.
- 포맷: JSON은
{}와 []를 사용해 구조를 나타내고, 문자열은 항상 쌍따옴표로 둘러싸야 합니다. YAML은 들여쓰기를 사용해 계층을 나타내며, 쌍따옴표 없이도 문자열을 표현할 수 있습니다.
/api-docs 경로의 JSON 문서 활용
/api-docs 경로에서 제공되는 JSON 문서는 Swagger UI나 다른 도구에서 API를 문서화하고 시각화하는 데 사용됩니다. 이 JSON은 OpenAPI 스펙에 따라 구성되어 있으므로, API의 구조, 경로, 파라미터 등에 대한 상세 정보를 포함하고 있습니다.
- 재활용: JSON 문서는 다른 시스템에서 API를 통합하거나, 클라이언트 코드를 생성하는 데 사용될 수 있습니다. 또한, API 테스팅 도구나 다른 문서화 도구에서도 활용될 수 있습니다.
YAML로의 변환
JSON 문서를 다시 YAML 포맷으로 변환하는 것은 가능합니다. 이 과정은 간단한 변환 도구나 스크립트를 통해 수행할 수 있으며, 온라인에서 제공하는 여러 도구를 사용할 수도 있습니다.
- 온라인 변환 도구: 웹에서 제공되는 여러 "JSON to YAML" 변환 도구를 사용할 수 있습니다.
- 프로그래밍을 통한 변환: Node.js와 같은 환경에서는 다음과 같이 JSON을 YAML로 변환할 수 있는 코드를 작성할 수 있습니다.
const yaml = require('js-yaml');
const fs = require('fs');
// 예를 들어, JSON 파일을 읽고 YAML로 변환
const jsonDocument = fs.readFileSync('./api-docs.json', 'utf8');
const yamlDocument = yaml.dump(JSON.parse(jsonDocument));
fs.writeFileSync('./api-spec.yaml', yamlDocument);
위 코드에서는 js-yaml 라이브러리를 사용하여 JSON 문서를 YAML 문서로 변환하고 있습니다. 이 방법을 통해 /api-docs에서 제공하는 JSON 문서를 다시 YAML 형식으로 저장하고 활용할 수 있습니다.
이러한 변환 작업을 통해 JSON으로 제공된 API 스펙을 다른 포맷으로 쉽게 변경하여 다양한 용도로 사용할 수 있습니다.