JSON ke YAML OpenAPI & Swagger

Konversi spesifikasi API antara JSON dan YAML tanpa merusak path $ref atau kode respons.

Opsi output

JSONinput

Kosong

YAMLoutput

Output YAML muncul di sini

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.

Muat dari URL

File diambil langsung oleh browser Anda, sehingga server harus mengizinkan permintaan lintas asal (cross-origin).

Pintasan keyboard

Ctrl / ⌘ + Enter Konversi sekarang
Ctrl / ⌘ + S Unduh output
Alt + Shift + C Salin output
Alt + Shift + F Perbaiki dan format input JSON
Alt + Shift + S Tukar arah
Alt + Shift + T Beralih antara tampilan kode, pohon, dan peta
Ctrl / ⌘ + Z Urungkan, termasuk Format, Perbaiki, dan Hapus
Esc Keluar dari layar penuh
Ukuran teks editor

Pointer $ref dan kode respons tetap valid

Dua detail yang sering merusak spesifikasi yang dikonversi manual: # yang memulai komentar YAML, dan kode status yang berubah menjadi integer. Keduanya ditangani.

openapi.json
{
  "paths": {
    "/pets/{id}": {
      "get": {
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Pet"
                }
              }
            }
          },
          "4XX": {
            "description": "Client error"
          }
        }
      }
    }
  }
}
openapi.yaml
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.

Lint hasilnya

Setelah konversi, jalankan linter untuk memeriksa spesifikasinya sendiri, bukan hanya sintaksnya. Di sini, setiap $ref lokal diperiksa saat Anda mengedit.

bash
# Lint the converted spec (OpenAPI 3.x and Swagger 2.0)
npx @redocly/cli lint openapi.yaml

JSON atau YAML untuk spesifikasi API?

YAML untuk menulis

Deskripsi panjang lebih mudah dibaca sebagai teks blok YAML, dan komentar memungkinkan Anda memberi catatan pada spesifikasi untuk reviewer.

JSON untuk tooling

Generator kode, gateway, dan SDK sering kali memuat JSON paling cepat, dan banyak yang menyajikan spesifikasi di /openapi.json.

Dokumen yang sama

Kedua format mendeskripsikan API yang sama. Konversi bebas ke arah mana pun; tidak ada bagian spesifikasi yang hilang.

Alat lainnya

Konverter, validator, dan panduan langkah demi langkah untuk setiap tempat JSON dan YAML bertemu.

Pertanyaan yang sering diajukan

Bagaimana cara mengonversi file OpenAPI JSON ke YAML?

Tempel atau unggah openapi.json lalu salin YAML dari panel kanan, atau unduh sebagai openapi.yaml. Struktur, pointer $ref, contoh, dan deskripsi dipertahankan persis.

Apakah ini berfungsi untuk Swagger 2.0 selain OpenAPI 3?

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.

Mengapa $ref: '#/components/...' diberi tanda kutip?

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.

Mengapa kode respons ditulis sebagai '200'?

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.

Bagaimana cara mengonversi OpenAPI YAML kembali ke JSON?

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.