YAML untuk penulisan
Penerangan panjang lebih mudah dibaca sebagai teks blok YAML, dan komen membolehkan anda menganotasi spesifikasi untuk penyemak.
Tukar spesifikasi API antara JSON dan YAML tanpa merosakkan laluan $ref atau kod respons.
Setiap baris output, dalam format lalai, di sebelah laluan nilai yang dikandungnya. Klik baris untuk menyalin laluan.
Dijalankan sepenuhnya dalam pelayar anda: tiada apa-apa dimuat naik. Had penggunaan wajar dikenakan (5 MB setiap input, penukaran berhad kadar) untuk mencegah spam dan bot.
Dua butiran merosakkan spesifikasi yang ditukar secara manual: # yang memulakan komen YAML, dan kod status yang menjadi integer. Kedua-duanya diuruskan.
{
"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 Tukar kepada Ditulis tangan, tanpa petikan untuk melihat $ref bertukar menjadi null dan hos wildcard gagal dihurai.
Selepas menukar, jalankan linter untuk menyemak spesifikasi itu sendiri, bukan hanya sintaksnya. Di sini, setiap $ref setempat disemak semasa anda menyunting.
# Lint the converted spec (OpenAPI 3.x and Swagger 2.0)
npx @redocly/cli lint openapi.yaml Penerangan panjang lebih mudah dibaca sebagai teks blok YAML, dan komen membolehkan anda menganotasi spesifikasi untuk penyemak.
Penjana kod, gateway dan SDK selalunya memuatkan JSON paling pantas, dan banyak yang menyediakan spesifikasi di /openapi.json.
Kedua-dua format menerangkan API yang sama. Tukar dengan bebas ke mana-mana arah; tiada apa-apa dalam spesifikasi yang hilang.
Penukar, pengesah dan panduan langkah demi langkah untuk setiap tempat JSON dan YAML bertemu.
Tampal atau muat naik openapi.json dan salin YAML daripada panel sebelah kanan, atau muat turunnya sebagai openapi.yaml. Struktur, penuding $ref, contoh dan penerangan dikekalkan tepat.
Ya. Penukar berfungsi pada struktur dokumen, jadi spesifikasi Swagger 2.0, OpenAPI 3.0 dan OpenAPI 3.1 ditukar dengan cara yang sama, dalam kedua-dua arah.
Dalam YAML, # memulakan komen apabila ia mengikuti ruang. Tanpa petikan, semua selepas $ref: akan dianggap sebagai komen dan rujukan itu akan kosong. Penukar memberi petikan secara automatik.
OpenAPI mewajibkan kod respons sebagai kunci rentetan. 200 tanpa petikan ialah integer dalam YAML; kebanyakan alat menerimanya, tetapi pengesah yang ketat tidak. Petikan memastikan spesifikasi kekal sah di mana-mana.
Tukar arah kepada YAML → JSON dengan togol di atas editor, atau gunakan penukar YAML kepada JSON. Sauh dalam YAML dikembangkan, kerana JSON tidak mempunyai rujukan sebegitu.