Ekstensi Spesifikasi OpenAPI Apidog

Apidog mendukung ekstensi spesifikasi OpenAPI/Swagger kustom yang meningkatkan kemampuan desain dan manajemen API. Ekstensi ini memungkinkan Anda menentukan metadata tambahan untuk endpoint API Anda, seperti organisasi folder, status endpoint, dan informasi pengelola.

Panduan referensi ini mendokumentasikan ekstensi x-apidog-* kustom yang dapat digunakan dalam spesifikasi OpenAPI/Swagger Anda untuk berintegrasi secara mulus dengan fitur Apidog.

Menentukan Folder Tempat Endpoint Berada

Apidog akan memprioritaskan penggunaan bidang x-apidog-folder untuk mengatur endpoint. Jika bidang ini tidak ada, Apidog akan menggunakan nilai pertama dalam bidang tags.

Gunakan garis miring / untuk memisahkan folder multi-tingkat. Perhatikan bahwa baik garis miring terbalik \ maupun garis miring / adalah karakter khusus yang memerlukan escaping. Untuk merepresentasikan karakter garis miring /, gunakan \/, dan untuk merepresentasikan karakter \, gunakan \\.

Contoh:

"paths": {
  "/pets": {
     "post": {
         ...
         "operationId": "addPet",     
         "x-apidog-folder": "Pet Store/Pet Information"
     }
  }
}

Contoh Anotasi Swagger:

Organisasi Folder

Gunakan nama folder yang deskriptif untuk mengatur endpoint Anda secara logis. Ini meningkatkan navigasi dan membantu anggota tim menemukan endpoint dengan cepat.

Status Endpoint

Periksa status endpoint menggunakan bidang x-apidog-status. Ini memungkinkan Anda melacak siklus hidup pengembangan setiap endpoint API.

Nilai Status yang Tersedia

Status	Deskripsi
designing	(Sedang Dirancang)
pending	(Tertunda)
developing	(Sedang Dikembangkan)
integrating	(Sedang Diintegrasikan)
testing	(Sedang Diuji)
tested	(Telah Diuji)
released	(Dirilis)
deprecated	(Tidak Direkomendasikan)
exception	(Pengecualian)
obsolete	(Usang)
to be deprecated	(Akan Tidak Direkomendasikan)

Contoh:

"paths": {
    "/pets": {
        "post": {
            ...
            "operationId": "addPet",     
            "x-apidog-status": "released"
        }
    }
}

Contoh Anotasi Swagger:

Pelacakan Status

Status endpoint membantu tim mengoordinasikan upaya pengembangan dan memahami API mana yang siap digunakan dalam produksi.

Pengelola

Tentukan pengelola untuk sebuah endpoint menggunakan bidang x-apidog-maintainer. Nilainya adalah nama panggilan atau nama pengguna dari pengguna Apidog dalam tim.

Contoh:

"paths": {
    "/pets": {
        "post": {
            ...   
            "x-apidog-maintainer": "david"
        }
    }
}

Contoh Anotasi Swagger:

Penting

Nilai pengelola harus cocok dengan nama pengguna atau nama panggilan anggota tim yang sudah ada di Apidog agar penugasan dapat dilakukan dengan benar.

Ekstensi Spesifikasi OpenAPI Apidog

Menentukan Folder Tempat Endpoint Berada#

Status Endpoint#

Nilai Status yang Tersedia#

Pengelola#

Menentukan Folder Tempat Endpoint Berada

Status Endpoint

Nilai Status yang Tersedia

Pengelola