작성에는 YAML
긴 설명은 YAML 블록 텍스트로 읽기 더 좋고, 주석으로 검토자를 위한 메모를 남길 수 있습니다.
$ref 경로나 응답 코드를 깨뜨리지 않고 API 명세를 JSON과 YAML 사이에서 변환합니다.
출력의 각 줄을 기본 서식으로 보여 주고, 그 줄에 담긴 값의 경로를 옆에 표시합니다. 줄을 클릭하면 경로가 복사됩니다.
전부 브라우저에서 실행되며 아무것도 업로드되지 않습니다. 스팸과 봇을 막기 위해 공정 사용 제한(입력당 5 MB, 변환 횟수 제한)이 적용됩니다.
직접 변환한 명세를 망가뜨리는 두 가지가 있습니다. YAML 주석을 시작하는 #, 그리고 정수가 되어 버리는 상태 코드입니다. 둘 다 처리됩니다.
{
"paths": {
"/pets/{id}": {
"get": {
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Pet"
}
}
}
},
"4XX": {
"description": "Client error"
}
}
}
}
}
} paths:
/pets/{id}:
get:
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
4XX:
description: Client error 따옴표 없이 직접 작성으로 바꾸면 $ref가 null이 되고 와일드카드 호스트가 파싱에 실패하는 것을 볼 수 있습니다.
변환한 뒤에는 린터를 실행해 구문뿐 아니라 명세 자체도 검사하세요. 여기서는 편집하는 동안 모든 로컬 $ref를 검사합니다.
# Lint the converted spec (OpenAPI 3.x and Swagger 2.0)
npx @redocly/cli lint openapi.yaml 긴 설명은 YAML 블록 텍스트로 읽기 더 좋고, 주석으로 검토자를 위한 메모를 남길 수 있습니다.
코드 생성기, 게이트웨이, SDK는 JSON을 가장 빠르게 불러오는 경우가 많고, 상당수가 명세를 /openapi.json으로 제공합니다.
두 형식은 같은 API를 설명합니다. 어느 방향으로든 자유롭게 변환하세요. 명세의 내용은 전혀 손실되지 않습니다.
JSON과 YAML이 만나는 모든 곳을 위한 변환기, 검사기, 단계별 가이드.
openapi.json을 붙여넣거나 업로드하고, 오른쪽 패널에서 YAML을 복사하거나 openapi.yaml로 다운로드하세요. 구조, $ref 포인터, 예시, 설명은 그대로 유지됩니다.
네. 변환기는 문서 구조를 기준으로 동작하므로 Swagger 2.0, OpenAPI 3.0, OpenAPI 3.1 명세가 모두 양방향으로 같은 방식으로 변환됩니다.
YAML에서 공백 뒤의 #은 주석의 시작입니다. 따옴표가 없으면 $ref: 뒤의 모든 내용이 주석으로 처리되어 참조가 비게 됩니다. 변환기는 자동으로 따옴표를 붙입니다.
OpenAPI는 응답 코드가 문자열 키여야 합니다. 따옴표 없는 200은 YAML에서 정수입니다. 대부분의 도구는 이를 허용하지만 엄격한 검사기는 허용하지 않습니다. 따옴표를 붙이면 어디서나 명세가 유효하게 유지됩니다.
편집기 위의 토글로 변환 방향을 YAML → JSON으로 바꾸거나, YAML JSON 변환기를 사용하세요. JSON에는 그런 종류의 참조가 없으므로 YAML의 앵커는 펼쳐집니다.