​
Mendeskripsikan API Anda

Ada banyak alat hebat online untuk mempelajari dan membuat dokumen OpenAPI. Berikut adalah favorit kami:

Panduan OpenAPI Swagger adalah untuk OpenAPI v3.0, tetapi hampir semua informasi berlaku untuk v3.1. Untuk informasi lebih lanjut tentang perbedaan antara v3.0 dan v3.1, lihat OpenAPI’s blog post.

​
Menentukan URL untuk API Anda

Dalam dokumen OpenAPI, endpoint API yang berbeda ditentukan oleh jalurnya, seperti /users/{id}, atau mungkin hanya /. Untuk menentukan URL dasar yang akan ditambahkan jalur-jalur ini, OpenAPI menyediakan bidang servers. Bidang ini diperlukan untuk menggunakan beberapa fitur Mintlify seperti API Playground. Baca cara mengkonfigurasi bidang servers di dokumentasi Swagger.

API Playground akan menggunakan URL server ini untuk menentukan ke mana mengirim permintaan. Jika beberapa server ditentukan, dropdown akan muncul untuk memungkinkan beralih antar server. Jika tidak ada server yang disediakan, API Playground akan menggunakan mode sederhana, karena tidak ada cara untuk mengirim permintaan.

Jika endpoint yang berbeda dalam API Anda ada di URL yang berbeda, Anda dapat mengganti bidang server untuk jalur atau operasi tertentu.

​
Menentukan autentikasi

Hampir semua API memerlukan beberapa metode autentikasi. OpenAPI menyediakan bidang securitySchemes untuk mendefinisikan metode autentikasi yang digunakan di seluruh API Anda, dengan konfigurasi sederhana untuk jenis autentikasi yang paling umum - Basic, Bearer, dan API Keys. Untuk menerapkan metode autentikasi ini ke endpoint Anda, OpenAPI menggunakan bidang security. Sintaks untuk mendefinisikan dan menerapkan autentikasi agak tidak intuitif, jadi pastikan untuk memeriksa dokumentasi dan contoh Swagger tentang topik ini.

Deskripsi API dan API Playground akan menambahkan bidang autentikasi berdasarkan konfigurasi keamanan dalam dokumen OpenAPI Anda.

Jika endpoint yang berbeda dalam API Anda memerlukan metode autentikasi yang berbeda, Anda dapat mengganti bidang keamanan untuk operasi tertentu.