Troubleshooting

Halaman API itu rumit. Akibatnya, ada banyak hal yang bisa salah. Berikut adalah daftar masalah umum yang kami lihat pelanggan hadapi:

Semua halaman OpenAPI saya benar-benar kosong

Dalam skenario ini, kemungkinan besar Mintlify tidak dapat menemukan dokumen OpenAPI Anda, atau dokumen OpenAPI Anda tidak valid.

Menjalankan mint dev secara lokal seharusnya mengungkapkan beberapa masalah ini.

Untuk memverifikasi bahwa dokumen OpenAPI Anda akan lulus validasi:

1. Kunjungi validator ini
2. Beralih ke tab “Validate text”
3. Tempel dokumen OpenAPI Anda
4. Klik “Validate it!”

Jika kotak teks yang muncul di bawah memiliki batas hijau, dokumen Anda telah lulus validasi. Ini adalah paket validasi yang sama persis yang digunakan Mintlify untuk memvalidasi dokumen OpenAPI, jadi jika dokumen Anda lulus validasi di sini, ada kemungkinan besar masalahnya ada di tempat lain.

Selain itu, Mintlify tidak mendukung OpenAPI 2.0. Jika dokumen Anda menggunakan versi spesifikasi ini, Anda mungkin mengalami masalah ini. Anda dapat mengonversi dokumen Anda di editor.swagger.io (di bawah Edit > Convert to OpenAPI 3):

Salah satu halaman OpenAPI saya benar-benar kosong

Ini biasanya disebabkan oleh salah eja pada bidang openapi dalam metadata halaman. Pastikan metode HTTP dan path cocok persis dengan metode HTTP dan path dalam dokumen OpenAPI.

Berikut adalah contoh bagaimana hal-hal mungkin salah:

get-user.mdx

---
openapi: "GET /users/{id}/"
---

openapi.yaml

paths:
  "/users/{id}":
    get: ...

Perhatikan bahwa path di bidang openapi memiliki garis miring di akhir, sedangkan path dalam dokumen OpenAPI tidak.

Masalah umum lainnya adalah nama file yang salah eja. Jika Anda menentukan dokumen OpenAPI tertentu dalam bidang openapi, pastikan nama filenya benar. Misalnya, jika Anda memiliki dua dokumen OpenAPI openapi/v1.json dan openapi/v2.json, metadata Anda mungkin terlihat seperti ini:

api-reference/v1/users/get-user.mdx

---
openapi: "v1 GET /users/{id}"
---

Permintaan dari API Playground tidak berfungsi

Jika Anda memiliki domain kustom yang dikonfigurasi, ini bisa jadi masalah dengan reverse proxy Anda. Secara default, permintaan yang dibuat melalui API Playground dimulai dengan permintaan POST ke

/api/request path pada situs docs. Jika reverse proxy Anda dikonfigurasi untuk hanya mengizinkan permintaan GET, maka semua permintaan ini akan gagal. Untuk memperbaikinya, konfigurasikan reverse proxy Anda untuk mengizinkan permintaan POST ke path /api/request.

Atau, jika reverse proxy Anda mencegah Anda menerima permintaan POST, Anda dapat mengonfigurasi Mintlify untuk mengirim permintaan langsung ke backend Anda dengan pengaturan api.playground.proxy di docs.json, seperti yang dijelaskan di sini. Ini mungkin mengharuskan Anda untuk mengonfigurasi CORS di server Anda, karena permintaan ini sekarang akan datang langsung dari browser pengguna Anda.