Softonic

Pemeriksaan Kolom Wajib OpenAPI

Langkah 1 / 2
Berikutnya

Sebelum menyerahkan deskripsi API kepada rekan tim, klien, atau generator dokumentasi, pastikan kolom wajibnya sudah ada. Tempel dokumen Anda di atas, dan alat ini akan memastikan kolom version, info.title, info.version, dan paths, serta mendaftar apa pun yang belum ada.

Cara memeriksa kolom wajib

  1. 1

    Tempel dokumen

    Tempel spesifikasi Anda dalam format JSON atau YAML, meskipun masih dalam tahap pengerjaan.

  2. 2

    Jalankan pemeriksaan

    Lanjutkan ke langkah hasil. Setiap kolom yang hilang muncul sebagai galat tersendiri.

  3. 3

    Tambahkan yang kurang

    Tambahkan kolom yang tercantum ke berkas Anda dengan memakai cuplikan di bawah.

  4. 4

    Periksa ulang

    Tempel spesifikasi yang sudah diperbarui dan jalankan lagi hingga tidak ada galat yang ditampilkan.

Empat bagian wajib

Kolom Letaknya di mana Contoh
Kolom version Tingkat atas openapi: 3.0.3 atau swagger: "2.0"
info.title Di dalam info title: Orders API
info.version Di dalam info version: 1.0.0
paths Tingkat atas paths: dengan setidaknya satu rute pertama

Nilai info.version adalah versi API Anda sendiri, bukan versi spesifikasi OpenAPI. Orang sering melewatkannya karena versi spesifikasi sudah tertulis di bagian atas.

Contoh dengan semua bagian hilang

servers:
  - url: https://api.example.com

Dokumen kecil ini tidak memiliki satu pun bagian wajib. Laporannya mendaftar tiga galat:

Temuan Jenis
Missing ‘openapi’ or ‘swagger’ version field. Galat
Missing ‘info’ object. Galat
Missing ‘paths’ object. Galat

Jika seluruh objek info tidak ada, alat hanya melaporkan satu galat itu dan tidak mendaftar title serta version secara terpisah. Tambahkan info dengan kedua kolom, dan pemeriksaan berikutnya akan melaporkan jika salah satunya masih kurang.

Kerangka awal

openapi: 3.0.3
info:
  title: Orders API
  version: 1.0.0
paths:
  /orders:
    get:
      summary: List orders

Kerangka ini lolos setiap pemeriksaan kolom wajib. Ganti nama dengan nama Anda sendiri dan kembangkan dari sana. Respons, skema, dan keamanan tidak termasuk dalam pemeriksaan ini.

Kapan menjalankan pemeriksaan ini

Jalankan saat Anda memulai spesifikasi baru dari nol, setelah menghasilkannya dari kode, dan sebelum mengirimkannya kepada siapa pun yang akan mengimpornya ke alat lain. Banyak pengimpor berhenti pada kolom wajib pertama yang hilang dengan pesan singkat, sehingga menangkap semuanya sekaligus menghemat beberapa putaran. Ini juga pengingat berguna bagi pemula, yang sering lupa info.version atau tidak menyertakan paths saat membuat sketsa API.

Setelah kolom wajib lolos, tambahan yang berguna berikutnya adalah description singkat di bawah info, entri servers, dan operationId pada setiap operasi. Tidak satu pun dari ini diperiksa di sini, tetapi membuat spesifikasi lebih mudah dibaca dan diubah menjadi kode klien.

Pertanyaan yang Sering Diajukan

Tidak. Kolom openapi menyatakan versi spesifikasi yang Anda gunakan. info.version adalah versi API Anda sendiri, misalnya 1.0.0.

Kunci harus ada sebagai objek, dan pemeriksaan ini tidak mewajibkan adanya rute di dalamnya. Tambahkan rute sungguhan sebelum mempublikasikan.

Pemeriksaan title dan version hanya berjalan ketika objek info ada. Tambahkan objeknya, lalu jalankan ulang untuk melihat apakah kolomnya sudah lengkap.

Tidak. Di sini hanya kolom version, info, title, version, dan paths yang wajib. Detail di tingkat operasi tidak diperiksa.

Alat Terkait

Generator Konfigurasi Webpack

Buat webpack.config.js untuk webpack 5 bagi JavaScript biasa, React, atau Vue: TypeScript, Babel, CSS atau Sass, gambar, HtmlWebpackPlugin, server pengembangan, dan baris npm install.

Referensi Tabel ASCII

Tabel ASCII lengkap dari 0 sampai 127 dengan desimal, heksadesimal, oktal, biner, dan referensi karakter numerik HTML untuk setiap karakter, termasuk kode kontrol seperti NUL, LF, dan DEL.

Referensi Karakter HTML

Daftar entitas HTML yang dapat dicari, beserta kode bernama dan kode numeriknya, serta fitur salin dengan satu klik untuk karakter khusus dan simbol.

Validator XSD

Validasi dokumen XML terhadap skema XSD dan laporkan ketidakcocokan elemen dan tipe dengan nomor baris persis.

Dekoder Protocol Buffers

Dekode byte wire-format Protobuf secara lokal dari hex, Base64, Base64URL, teks, atau file; periksa kandidat field yang tepat dan ekspor laporan privat.

XML Formatter

Pretty-print dokumen XML dengan indentasi konsisten dan tangkap kesalahan well-formedness lengkap dengan nomor baris persis.

Alat ini tersedia dalam bahasa lain

Panduan dan contoh penggunaan