YAML за писане
Дългите описания се четат по-добре като блоков текст в YAML, а коментарите ви позволяват да анотирате спецификацията за рецензентите.
Конвертирайте API спецификации между JSON и YAML, без да чупите пътищата в $ref или кодовете на отговорите.
Всеки ред от резултата, във форматиране по подразбиране, до пътя на стойността, която съдържа. Щракнете върху ред, за да копирате пътя.
Работи изцяло във вашия браузър: нищо не се качва. Прилагат се ограничения за честна употреба (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. Котвите в YAML се разгръщат, тъй като JSON няма препратки от този вид.