Swagger , uygulamanızın RESTful API belgesini otomatik olarak oluşturan özel bir araçtır.
Avantajı, yalnızca uygulamanın tüm uç noktalarına bakmanıza değil, aynı zamanda bir istek göndererek ve yanıt alarak bunları hemen eylemde test etmenize izin vermesi gerçeğinde yatmaktadır.
Swagger erişmek için, yayınlanan uygulamada Preview düğmesine basmanız ve gerekli yayınlama planının adına tıklamanız gerekir ( Deploy Plan ).
Yeni açılan pencerede, bu uç noktalarla ilişkili kullanılabilir uç noktaların ve yöntemlerin bir listesi gösterilir. Bazı istekler yalnızca belirli yetkili kullanıcı grupları için kullanılabilir ( Endpoints bölümündeki her bir özel istek için Yetkilendirme Auth module Middleware Yazılımına bakın). Yalnızca yetkili kullanıcılar için izin verilen istekler için bir Bearer Token gereklidir.
Bu belirteci almak için ilgili uç noktaya doğrudan Swagger erişebilirsiniz ( Auth bölümü, POST /auth request).
Bir belirteç almak için Try it out basın ve kullanıcı adı ve şifreyi girin.
İstek Execute gönderilecektir. Başarıyla giderse, Bearer token değerine sahip bir token alanı göreceksiniz.
Yetkili bir kullanıcı belirteci almanın ikinci yolu, belirtecin konuşlandırılmış uygulamanın istek gövdesinde bulunabilmesidir.
- Geliştirici aracını açmak için web tarayıcınızda F12 tuşuna basın.
- Dağıtılan uygulamanızdaki herhangi bir isteği gönderin (örneğin tabloları güncellemek için). Bu isteği gönderen kullanıcının bu uç noktaya erişim yetkisi olması gerekir.
- Network sekmesini açın ve ilgili isteği bulun.
- Headers sekmesine gidin ve Başlıkları Request Headers bölümünü bulun. Bearer token Authorization altında sunulacaktır.
Authorize basarak ve önceki adımda kopyaladığınız değeri yapıştırarak Swagger Bearer token sağlayın.
Test istekleri için istediğiniz grubu ve yürütmek istediğiniz yöntemi seçin. Try it out basın ve istek giriş parametrelerini girin. Yanıtı Execute için Yürüt'e tıklayın.
İstek sunucu tarafından doğru bir şekilde işlenirse en çok beklenen yanıt 200 koduna sahiptir ve yanıt yapısının nasıl görünmesi gerektiğini gösterir.
401 - gerekli yetkilendirme belirteci eksik veya geçersiz olduğundan istek başarıyla tamamlanamadı.
404 - istek başarıyla işlendi, ancak istenen kaynak bulunamadı.
422 - isteğin girişine yanlış parametreler iletildi.
500 - sunucu tarafından istek işlenirken bir hata oluştu.
Özel Hatayı Yükselt
Özel BP'ler ve ilgili istekler için, BP düzenleyicisindeki Raise Error bloğunu kullanarak açıklamalar içeren özel hata kodları oluşturmak mümkündür. Böyle bir işlemin bir örneği aşağıdadır:
Bu durumda, yukarıdaki BP ile ilişkili uç noktaya yapılan istek başarısız olursa, sunucu DB: Create Candidate block yürütürken hata metnini içeren bir 418 hatası verir. Bu örnekteki hata kodu, kullanıcının belirttiği herhangi biri olabilir.
Not: HTTP 418 I'm a teapot client hata yanıt kodu, sunucunun kalıcı olarak bir çaydanlık olduğu için kahve demlemeyi reddettiğini gösterir. Geçici olarak kahvesi bitmiş birleşik bir kahve/çaydanlık bunun yerine 503 döndürmelidir. Bu hata, 1998 ve 2014'te April Fools'un şakalarında tanımlanan Hyper Text Coffee Pot Control Protocol bir referanstır.
