JSON kepada YAML OpenAPI & Swagger

Tukar spesifikasi API antara JSON dan YAML tanpa merosakkan laluan $ref atau kod respons.

Pilihan output

JSONinput

Kosong

YAMLoutput

Output YAML dipaparkan di sini

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.

Muatkan dari URL

Fail diambil terus oleh pelayar anda, jadi pelayan mesti membenarkan permintaan rentas asal.

Pintasan papan kekunci

Ctrl / ⌘ + Enter Tukar sekarang
Ctrl / ⌘ + S Muat turun output
Alt + Shift + C Salin output
Alt + Shift + F Baiki dan format input JSON
Alt + Shift + S Tukar arah
Alt + Shift + T Tukar antara paparan kod, pepohon dan peta
Ctrl / ⌘ + Z Buat asal, termasuk Format, Baiki dan Kosongkan
Esc Keluar skrin penuh
Saiz teks editor

Penuding $ref dan kod respons kekal sah

Dua butiran merosakkan spesifikasi yang ditukar secara manual: # yang memulakan komen YAML, dan kod status yang menjadi integer. Kedua-duanya diuruskan.

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

Tukar kepada Ditulis tangan, tanpa petikan untuk melihat $ref bertukar menjadi null dan hos wildcard gagal dihurai.

Lint hasilnya

Selepas menukar, jalankan linter untuk menyemak spesifikasi itu sendiri, bukan hanya sintaksnya. Di sini, setiap $ref setempat disemak semasa anda menyunting.

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 penulisan

Penerangan panjang lebih mudah dibaca sebagai teks blok YAML, dan komen membolehkan anda menganotasi spesifikasi untuk penyemak.

JSON untuk perkakas

Penjana kod, gateway dan SDK selalunya memuatkan JSON paling pantas, dan banyak yang menyediakan spesifikasi di /openapi.json.

Dokumen yang sama

Kedua-dua format menerangkan API yang sama. Tukar dengan bebas ke mana-mana arah; tiada apa-apa dalam spesifikasi yang hilang.

Lagi alatan

Penukar, pengesah dan panduan langkah demi langkah untuk setiap tempat JSON dan YAML bertemu.

Soalan lazim

Bagaimanakah cara menukar fail OpenAPI JSON kepada YAML?

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.

Adakah ia berfungsi untuk Swagger 2.0 dan juga OpenAPI 3?

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.

Mengapakah $ref: '#/components/...' diberi petikan?

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.

Mengapakah kod respons ditulis sebagai '200'?

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.

Bagaimanakah cara menukar OpenAPI YAML kembali kepada JSON?

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.