YAML untuk menulis
Deskripsi panjang lebih mudah dibaca sebagai teks blok YAML, dan komentar memungkinkan Anda memberi catatan pada spesifikasi untuk reviewer.
Konversi spesifikasi API antara JSON dan YAML tanpa merusak path $ref atau kode respons.
Setiap baris output, dengan format bawaan, di samping path nilai yang dikandungnya. Klik baris untuk menyalin path.
Berjalan sepenuhnya di browser Anda: tidak ada yang diunggah. Batas penggunaan wajar berlaku (5 MB per input, jumlah konversi dibatasi) untuk mencegah spam dan bot.
Dua detail yang sering merusak spesifikasi yang dikonversi manual: # yang memulai komentar YAML, dan kode status yang berubah menjadi integer. Keduanya ditangani.
{
"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 Beralih ke Ditulis manual, tanpa tanda kutip untuk melihat $ref berubah menjadi null dan host wildcard gagal di-parse.
Setelah konversi, jalankan linter untuk memeriksa spesifikasinya sendiri, bukan hanya sintaksnya. Di sini, setiap $ref lokal diperiksa saat Anda mengedit.
# Lint the converted spec (OpenAPI 3.x and Swagger 2.0)
npx @redocly/cli lint openapi.yaml Deskripsi panjang lebih mudah dibaca sebagai teks blok YAML, dan komentar memungkinkan Anda memberi catatan pada spesifikasi untuk reviewer.
Generator kode, gateway, dan SDK sering kali memuat JSON paling cepat, dan banyak yang menyajikan spesifikasi di /openapi.json.
Kedua format mendeskripsikan API yang sama. Konversi bebas ke arah mana pun; tidak ada bagian spesifikasi yang hilang.
Konverter, validator, dan panduan langkah demi langkah untuk setiap tempat JSON dan YAML bertemu.
Tempel atau unggah openapi.json lalu salin YAML dari panel kanan, atau unduh sebagai openapi.yaml. Struktur, pointer $ref, contoh, dan deskripsi dipertahankan persis.
Ya. Konverter bekerja pada struktur dokumen, sehingga spesifikasi Swagger 2.0, OpenAPI 3.0, dan OpenAPI 3.1 dikonversi dengan cara yang sama, di kedua arah.
Di YAML, # memulai komentar jika didahului spasi. Tanpa tanda kutip, semua yang ada setelah $ref: akan dianggap komentar dan referensinya menjadi kosong. Konverter memberi tanda kutip secara otomatis.
OpenAPI mewajibkan kode respons berupa kunci string. 200 tanpa tanda kutip adalah integer di YAML; sebagian besar alat menerimanya, tetapi validator yang ketat tidak. Tanda kutip menjaga spesifikasi tetap valid di mana saja.
Ganti arah ke YAML → JSON dengan tombol di atas editor, atau gunakan konverter YAML ke JSON. Anchor di YAML dijabarkan, karena JSON tidak memiliki referensi semacam itu.