İçe aktarılan bir API'nin dokümantasyonuna erişme ve güncelleme

Bir belirtimi içe aktardığınızda Restorm yalnızca istek oluşturmaz: API’nin dokümantasyonunu da korur — açıklamalar, modeller, güvenlik şemaları, örnekler, numaralandırmalar — ve onu içe aktarmanın oluşturduğu değişken klasörüne ekler.

Dokümantasyona erişme

Değişken klasörünün Belgeler sekmesi

Ana görünüm budur. İçe aktarmadan doğan değişken klasörünü açın: alt sekme çubuğunda Ortamlar, Özel değişkenler ve Notlar sekmelerinin yanında bir Belgeler sekmesi bulunur.

Sekme yalnızca klasör bir içe aktarmadan geliyorsa görünür — elle oluşturduğunuz bir değişken klasörünün gösterecek dokümantasyonu yoktur.

Diğer erişim yolları

Nereden	Elde ettiğiniz
Bir isteğin Belgeler sekmesi	Yalnızca o işlemin dokümantasyonu — içindekiler listesi ve genel bilgi bloğu olmadan. Yalnızca işlem belirtimde bulunabildiğinde görünür
Bir basit klasörün Belgeler sekmesi	O klasörün içerdiği işlemlerle sınırlı dokümantasyon
Değişken klasörünün giriş alt sekmesi	Belgeleri görüntüle kartı — “API belgelerine, modellere ve uç noktalara göz atın”
Karşılama ekranı (API kartı)	Belgeler hızlı bağlantısı
Başlık çubuğundaki arama motoru	Bir sonucun üzerine gelindiğinde dokümantasyonun önizlemesi

Görünümün içeriği

Yukarıdan aşağıya:

• API’nin başlığı ve açıklaması;
• bir bilgi bloğu: Version, Source format (kaynak URL’ye bir bağlantıyla), Server (şemalar, sunucu, temel yol), Contact, License, Terms of service, External docs;
• açıklamasıyla birlikte her etiket için bir bölüm;
• her işlem için bir blok: yöntem ve URL, özet, grup etiketi, varsa deprecated işareti, Security bölümü (şema türü, OAuth 2 akışları, kapsamlar) ve katlanabilir bir Example payload;
• Parameters ve Responses tabloları (durum kodları renklendirilir);
• Models — şemaların etkileşimli grafiği; gezinilebilir ve yakınlaştırılabilir;
• Polymorphism — oneOf / anyOf / allOf bileşimleri;
• Enums — numaralandırmalar, klasörün numaralandırmalarıyla birleştirilmiş olarak.

Note

Bu bölümlerin başlıkları (Models, Enums, Parameters, Responses, Security, Example payload) uygulamanın bütün dillerinde İngilizce gösterilir. Ekranda göreceğiniz hâlleriyle bulabilmeniz için burada olduğu gibi bırakılmıştır.

Dokümantasyondan istek oluşturma

Her işlem bloğunda, o işlem için önceden yapılandırılmış bir istek oluşturan bir + Add düğmesi bulunur. Bir içe aktarma kısmi kaldığında ya da belirtimde yeni bir işlem belirdiğinde en kısa yol budur.

Gezinme ve arama

Sağda sabitlenmiş bir içindekiler listesi vardır — Overview, Operations, Models, Enums bölümleri — katlanabilir ve yeniden boyutlandırılabilir. Bir modele tıklamak grafiğe kadar kaydırır ve karşılık gelen düğümü orada ortalar.

Kısayol	Etki
Ctrl+F / Cmd+F	Dokümantasyon içinde aramayı açar
F3 / Enter	Sonraki eşleşme
Shift+F3 / Shift+Enter	Önceki eşleşme
Esc	Aramayı kapatır

Bir sayaç, sonuçlar içindeki konumu gösterir.

Dokümantasyonu güncelleme

Bir belirtim zamanla değişir. Restorm kaynağı yeniden alıp farkı uygulayabilir — dokümantasyon ve istekler — hem de çalışmanızın üzerine yazmadan.

Yalnızca URL ile yapılan içe aktarmalar için

Yeniden eşitleme yalnızca klasör bir URL’den içe aktarılmışsa kullanılabilir. Dosyadan ya da yapıştırarak yapılan bir içe aktarma kaynak kaydetmez ve yenileme düğmesi görünmez: giriş alt sekmesi o zaman “Bu klasör içe aktarılabilir bir kaynaktan oluşturulmadı.” mesajını gösterir.

Bu URL arayüzde sonradan değiştirilemez. Kaynağı değiştirmek için içe aktarmayı yeniden yapın.

Düğme nerede

Birbirine denk iki giriş noktası:

1. değişken klasörünün giriş alt sekmesi, API spec güncellemeleri bölümü — URL, Son içe aktarma ve Son kontrol bilgilerini gösterir ve Yenile düğmesini taşır;
2. kenar ağacında klasöre sağ tıklama → Yenile.

Otomatik denetim yoktur

Restorm belirtimlerinizi arka planda izlemez ve yeni bir sürümün çıktığını size bildirmez. Denetimi her zaman siz başlatırsınız.

Neler olur

1. Alma sırasında bir “API spec yenileniyor…” penceresi görünür. URL’nin ve başlıkların {{variables}} ifadeleri çözülür ve eklenmiş kimlik doğrulama rotası önceden oynatılır.
2. Restorm, alınan kaynağın parmak izini son içe aktarmada kaydedilenle karşılaştırır.
3. Hiçbir şey değişmemişse → “API spec güncel.”, ve iş biter.
4. Bir şey değişmişse (ya da alma başarısız olmuşsa) → yeniden eşitleme sihirbazı açılır.

Sihirbaz

• Kaynak URL salt okunur olarak gösterilir.
• Bir etiket, bir kimlik doğrulama rotası eklemenizi, değiştirmenizi ya da ayırmanızı sağlar; bir Custom headers alt menüsü de her yenilemede yeniden gönderilen sabit başlıklar eklemenizi sağlar.
• İki önizleme sekmesi:
  • Routes — yeni sürümde bulunan işlemlerin ağacı, filtre ve seçim ile. Klasörünüzde hâlihazırda bulunan işlemler kilitlidir ve her zaman işaretlidir; yalnızca yeni işlemlerden hangilerini ekleyeceğinizi seçersiniz;
  • Documentation — onaylamadan önce, yeni sürümün dokümantasyonu, salt okunur olarak.
• Onay düğmesi, seçilen yeni işlem sayısını gösterir; örneğin Apply update (3).

Note

Sihirbaz bugün, uygulamanın dili ne olursa olsun İngilizce gösterilir (“Refresh from source”, “Apply update”, “Routes” ve “Documentation” sekmeleri). Bu yüzden İngilizce başlıklar burada olduğu gibi verilmiştir.

Neyin değiştiği, neyin değişmediği

Önemli olan nokta şudur: belirtim, tanımladığı şey üzerinde yetkilidir; geri kalan her şeyde yetkili olan sizsiniz.

Öğe	Davranış
Bir isteğin adı	Asla değiştirilmez
Yöntem ve URL	Asla değiştirilmez
Mevcut parametreler, başlıklar ve yol parametreleri	Olduğu gibi korunur — değer, açıklama, etkinlik durumu
Belirtimin eklediği parametreler	Belirtimdeki varsayılan değerle ya da boş olarak eklenir
Belirtimden çıkarılan parametreler	İstekte korunur
Yeni işlem	Sıfırdan bir içe aktarmanın onu koyacağı yere eklenir (etiket klasörü dâhil)
Belirtimin kullanımdan kaldırılmış olarak işaretlediği işlem	İşaretlenir; ağaçta soluk görünür
Belirtimden kaybolan işlem	Kaldırılmış olarak işaretlenir; ağaçta üstü çizili görünür, çalıştırılabilir kalır ve asla silinmez
API dokümantasyonu ve numaralandırmalar	Yeni sürümle bütünüyle değiştirilir — Belgeler sekmesini yenileyen şey budur

Ağacınızdan hiçbir şey silinmez: kaynaktan kaybolan bir işlem işaretlenir, silinmez.

Kaynak kimlik doğrulama isterse

401 ya da 403 yanıtı, hata mesajı olduğu gibi gösterilerek sihirbazı açar (örneğin HTTP 401: Unauthorized). Bir kimlik doğrulama rotası ekleyin ya da sabit başlıklar tanımlayın; önizleme yeniden çalıştırılır.

Yeniden eşitlenebilir biçimler

On iki biçim yeniden eşitlemeyi destekler: Swagger 2.0, OpenAPI 3.x, GraphQL, gRPC, SOAP (WSDL), OData, AsyncAPI, Postman, Insomnia, Bruno, OpenRPC ve Smithy.

Diğerlerinin tamamında yeni bir içe aktarma yeni bir ağaç oluşturur. Tam liste Kaynaktan güncelleme sayfasındadır.