Apidog kullanılarak yayınlanmış çevrimiçi bir API belgesini açtığınızda, her bir uç noktanın yanında bir "Dene" düğmesi fark edeceksiniz. Bu düğmeye tıklamak, sayfanın sağ tarafında bir hata ayıklama panelini açar ve API'yi doğrudan dokümantasyon içinde test etmenizi sağlar.
Ancak, bu "Hata Ayıklama" özelliğinin kullanılabilirliği, platform içinde ne kadar iyi yapılandırdığınıza büyük ölçüde bağlıdır. Doğru URL kurulumu, kimlik doğrulama yapılandırması, net parametre yapısı ve eksiksiz örnek veriler gibi faktörler, hata ayıklama deneyimini önemli ölçüde etkiler.
Doğru yapılandırılmazsa, kullanıcılar parametreleri doldurmak için çok zaman harcayabilir veya hatta başarılı API çağrıları yapamayabilir, bu da ideal olmaktan uzaktır.
Yayınlanmış çevrimiçi dokümantasyonun mükemmel bir hata ayıklama deneyimi sunmasını sağlamak için Apidog'u nasıl etkili bir şekilde yapılandıracağımızı tartışalım.
Doğru URL Yapılandırması
Çoğu zaman, çevrimiçi dokümantasyon iyi görünür ancak "Dene" düğmesine tıklayıp bir istek gönderdiğinizde başarısız olur. En yaygın neden, uç noktanın yalnızca /pet/{petId} gibi bir yol içermesi ve yayınlama sırasında bir çalışma zamanı ortamı seçilmemiş olmasıdır.
Bu durum, protokol veya ana bilgisayar adı olmayan eksik istek URL'lerine yol açar ve istek gönderirken hatalara neden olur.
Bunu çözmek için, kullanıcıların doğru URL'ye erişebildiğinden emin olun. Apidog, ihtiyaçlarınıza bağlı olarak çevrimiçi dokümantasyon için URL'leri yapılandırmanın üç yolunu sunar.
1. Temel URL'leri Kullanın
Bu, önerilen yaklaşımdır. Uç noktada yalnızca /pet/{petId} gibi yolu tanımlayın ve "Ortam Yönetimi" bölümünde tam hizmet adresini (örn. https://product.example.com) bir Temel URL olarak yapılandırın.
API dokümantasyonunu yayınlarken uygun çalışma zamanı ortamını seçin. Apidog, Temel URL'yi uç nokta yoluyla otomatik olarak birleştirecektir. Her biri kendi Temel URL'sine sahip birden fazla çalışma zamanı ortamı da tanımlayabilirsiniz.
Çevrimiçi dokümantasyonda, kullanıcılar açılır listeden ortamları hızla değiştirebilir ve tüm uç nokta URL'leri buna göre güncellenecektir. Bu, API'leri farklı ortamlarda doğrulamayı kolaylaştırır.
Not: Protokol sorunlarına dikkat edin. Birçok tarayıcı, HTTPS sayfalarının HTTP API'lerini çağırmasını kısıtlar. API'niz HTTP kullanıyorsa, kullanıcılar bir HTTPS dokümantasyon sayfasında hata ayıklarken çapraz protokol sorunlarıyla karşılaşabilir.
2. Uç Noktalara Tam URL'leri Dahil Edin
Diğer bir seçenek de tam URL'yi doğrudan uç noktada belirtmektir, örneğin https://product.example.com/pet/{petId}.
Bu, seçilen çalışma zamanı ortamından bağımsız olarak tam istek URL'sinin görünür olmasını sağlar. Ancak, sunucu adreslerindeki değişiklikleri yönetmek zahmetli hale gelir, çünkü her uç noktayı ayrı ayrı güncellemeniz gerekir. Bu nedenle, bu yöntem daha az önerilir.
3. URL'lerde Değişkenleri Kullanın
Kullanıcıların hata ayıklama için URL'yi özelleştirmesini istiyorsanız, değişkenleri kullanabilirsiniz. Örneğin, "Ortam Yönetimi" bölümünde bir ortam değişkeni BaseURL oluşturun ve bunu Temel URL'de {{BaseURL}} olarak referans alın.
Çevrimiçi dokümantasyonda, kullanıcılar değişken adına tıklayabilir ve istedikleri URL'ye göre değiştirebilir.
Alternatif olarak, değişkenleri doğrudan uç noktada tanımlayabilirsiniz, örneğin {{BaseURL}}/pet/{petId}.
Çevrimiçi dokümantasyondaki o belirli uç nokta için, kullanıcılar isteği göndermek üzere değişkenin değerini ayarlayabilir.
Dokümantasyonu yayınlamadan önce, ortamdaki "başlangıç değerlerinin" hassas bilgiler (örn. kimlik doğrulama bilgileri) içermediğinden emin olun, çünkü bu değerler yayınlanan dokümantasyona dahil edilecek ve gizlilik riskleri oluşturabilir.
Doğru Kimlik Doğrulama Yapılandırması
Temel Kimlik Doğrulama Kurulumu
Başarılı uç nokta istekleri genellikle kimlik doğrulama gerektirir. Apidog, Taşıyıcı Belirteç (Bearer Token), API Anahtarı, OAuth2.0 ve Temel Kimlik Doğrulama dahil olmak üzere çeşitli kimlik doğrulama türlerini destekler.
Kimlik doğrulamayı uç nokta veya klasör düzeyinde bir güvenlik şeması kullanarak veya manuel olarak ayarlayarak yapılandırabilirsiniz.
Örneğin, kimlik doğrulama türü olarak Taşıyıcı Belirteç (Bearer Token) kullanıldığında, çevrimiçi dokümantasyondaki hata ayıklama panelinin üst kısmında bir "Belirteç" alanı görünür. Kullanıcılar, "Bearer" önekini manuel olarak eklemeye gerek kalmadan belirteç değerini doğrudan girebilirler. Apidog bunu otomatik olarak halleder, bu da yetkilendirme başlığını manuel olarak eklemekten daha kullanışlı hale getirir.
Bu kurulumun avantajı, kimlik doğrulama bilgilerinin birden fazla uç nokta arasında paylaşılabilmesidir. Birkaç uç nokta aynı güvenlik şemasını veya türünü kullanıyorsa, kimlik bilgilerini yalnızca bir kez girmeniz yeterlidir. Kimlik bilgilerindeki herhangi bir güncelleme, ilgili tüm uç noktalara otomatik olarak uygulanır.
Kimlik doğrulama bilgileri şifrelenir ve kullanıcının tarayıcısında yerel olarak depolanır, oturum başına yönetilir ve sekmeler ve pencereler arasında paylaşılır. Tarayıcı kapatıldığında temizlenirler, bu da yayınlanan dokümantasyonda hassas bilgilerin açığa çıkma riskini azaltır.
OAuth2.0 Yapılandırması
OAuth2.0 kimlik doğrulaması için, kullanıcıların hata ayıklama sırasında doğrudan belirteç oluşturmasını istiyorsanız, yetkilendirme sunucusu ayrıntılarını (örn. Yetkilendirme URL'si, Belirteç URL'si) projede yapılandırın.
OAuth2.0 güvenlik şeması kullanılırken, kullanıcıların hata ayıklama sırasında istemci kimliği, istemci gizli anahtarı vb. girmesi gerekecektir. Bir açılır pencere onları yetkilendirme süreci boyunca yönlendirecek ve elde edilen access_token sonraki API isteklerine otomatik olarak uygulanacaktır.
Net Parametre Yapıları Tasarlayın
Hata Ayıklama Panelinde Parametre Görüntüleme
Hata ayıklama paneli, uç nokta tasarımınıza göre parametre bölümlerini akıllıca görüntüler. Örneğin, uç nokta yalnızca Yol parametrelerini tanımlıyorsa, hata ayıklama paneli yalnızca Yol bölümünü gösterir ve gereksiz Sorgu veya Gövde bölümlerini önler.
Bu netlik, kullanıcıların alakasız bölümlerden rahatsız olmadan hangi parametreleri dolduracaklarını anlamalarına yardımcı olur.
Örnek Sağlayın
Uç noktaları tasarlarken, her parametrenin türünü ve gerekli niteliklerini doğru bir şekilde tanımlayın. Net açıklamalar ve örnekler ekleyin, çünkü bunlar hata ayıklama panelinde önceden doldurulacak ve kullanılabilirliği artıracaktır.
Gereksiz Başlıklardan Kaçının
Uç nokta Gövde parametrelerini tanımlıyorsa, Content-Type: application/json gibi başlıkları manuel olarak eklemeye gerek yoktur. Apidog, istekler sırasında bu tür başlıkları otomatik olarak halleder.
Benzer şekilde, kimlik doğrulama yapılandırılmışsa, bunu başlıklarda tekrarlamaktan kaçının. Kimlik doğrulama ayarları öncelik alır ve çakışan herhangi bir başlık yapılandırmasını geçersiz kılar.
Kapsamlı İstek Örnekleri Sunun
Karmaşık JSON istek gövdelerine sahip uç noktalar için, tasarım sırasında birden fazla istek gövdesi örneği sağlayın.
Kullanıcılar bu örnekleri hata ayıklama panelindeki açılır menüden seçebilir, bu da zaman kazandırır ve hataları azaltır.
Örnek verilerin gerçek dünya senaryolarına yakın olduğundan emin olun, ancak hassas bilgiler içermekten kaçının. Kullanıcılar bu örnekleri gerektiği gibi değiştirebilir.
Net Yanıt Örnekleri Yapılandırın
Bir istek gönderdikten sonra, hata ayıklama paneli durum kodları, başlıklar ve gövde dahil olmak üzere tam yanıtı görüntüler. Bir dokümantasyon oluşturucu olarak, kullanıcıların olası sonuçları anlamalarına yardımcı olmak için net yanıt örnekleri yapılandırın.
Her uç nokta için başarılı (200), hatalı istek (400) ve yetkisiz (401) gibi birden fazla yanıt örneği sağlayın.
Hata yanıtlarına özel dikkat gösterin, farklı senaryolar için hata kodlarını ve mesaj formatlarını açıkça açıklayın. Bu, kullanıcıların hata ayıklama sırasında sorunları hızlı bir şekilde belirlemesine ve çözmesine yardımcı olur.
Entegrasyon İçin Örnek Kod Sağlayın
Apidog, yaygın programlama dilleri için otomatik olarak örnek kod üretse de, üretilen kod iş ihtiyaçlarınızla tam olarak uyumlu olmayabilir. Bu gibi durumlarda, örnekleri özelleştirin.
"Proje Ayarları -> Uç Nokta Özellik Ayarları -> İstek Kodu Örnekleri" bölümünde hangi dillerin otomatik oluşturulmuş örneklere ihtiyaç duyduğunu yapılandırabilirsiniz.
Ek olarak, "Uç Nokta Açıklaması" bölümünde belirli uç noktalar için özel örnek kod yazabilirsiniz.
Bu, kullanıcıların çevrimiçi dokümantasyonda hem otomatik oluşturulmuş hem de özel örnekleri görmesini sağlayarak entegrasyonu kolaylaştırır.
Özet
Çevrimiçi dokümantasyonun hata ayıklama deneyimi, büyük ölçüde doğru yapılandırmaya bağlıdır. URL'leri, kimlik doğrulamayı, parametre yapılarını ve örnekleri dikkatlice ayarlayarak, kullanıcıların teknik ayrıntılara takılıp kalmadan API'nizle hızlı bir şekilde başlamalarını sağlayabilirsiniz.