Bu gönderi en son QWERTYU tarafından 2019-4-12 14:24 tarihinde düzenlenmiştir
GirişAPI geliştirme için asp.net Core kullanıldıktan sonra, API dokümantasyonu yazmak programcılar için acı verici bir iş olmalıdır, ancak dokümantasyon yazılmalı ve dokümantasyonun formatı için özel bir gereksinim yoksa, nihai dokümantasyon tamamen geliştiricinin ruh haline bağlıdır. Ya da daha detaylı ya da daha basit olabilir. Peki API dokümantasyonu oluşturmanın hızlı ve verimli bir yolu var mı? Cevap evet, Swagger REST API'lerinin en popüler dokümantasyon oluşturma araçlarından biridir!
Swagger'ı neden REST API'leri dokümantasyon oluşturma aracı olarak kullanıyoruz?- Swagger, geliştiricilerin API'leri hızlıca öğrenip denemeler yapabileceği etkileşimli bir API konsolu oluşturabilir.
- Swagger, çeşitli farklı platformlarda uygulamalar için istemci SDK kodu oluşturabilir.
- Swagger dosyaları, birçok farklı platformda kod yorumlarından otomatik olarak oluşturulabilir.
- Swagger'ın güçlü bir topluluğu ve birçok güçlü katkı sağlayıcısı var.
Swagger'ı asp.net çekirdekte API dokümantasyonu oluşturmak için nasıl kullanılır?- Swashbuckle.AspNetCore, ASP.NET Core Web API'si için Swagger dokümantasyonu üreten açık kaynaklı bir projedir.
- NSwag, Swagger UI veya ReDoc'u ASP.NET Core Web API'lerine entegre etmek için başka bir açık kaynak projesidir. API'ler için C# ve TypeScript istemci kodu oluşturmanın bir yolunu sunar.
Aşağıda Swashbuckle.AspNetCore örneği verilmiştir.Swashbuckle'ın bileşenleri nelerdir?- Swashbuckle.AspNetCore.Swagger: SwaggerDocument nesnesini JSON uç noktaları için Swagger nesne modeli ve ara yazılım olarak açığa çıkarır.
- Swashbuckle.AspNetCore.SwaggerGen: Rotalardan, kontrolörlerden ve modellerden doğrudan SwaggerDocument nesneleri üreten bir Swagger oluşturucu. Genellikle Swagger uç nokta ara yazılımıyla birleştirilerek otomatik olarak Swagger JSON'u açığa çıkarır.
- Swashbuckle.AspNetCore.SwaggerUI: Swagger arayüz aracının gömülü bir versiyonu. Swagger JSON'u, Web API'lerinin işlevselliğini tanımlayan özelleştirilebilir ve zengin deneyimler oluşturmak üzere yorumlar. Yaygın yöntemler için yerleşik test araçları içerir.
Swashbuckle vs2017 ile nasıl kurulur?
İlk yol: Paket Yöneticisi Konsolu penceresinden kurulum
- Diğer Windows > Paket Yöneticisi Konsolu > Görünümlere gidin
- TodoApi.csproj dosyasını içeren dizine gidin
- Lütfen aşağıdaki komutu yerine getirin · Install-Package Swashbuckle.AspNetCore
-
İkinci yol: Manage NuGet Packages diyalogundan:- Solution Explorer'da projeye sağ tıklayın > NuGet Paketlerini Yönetin
- Paket Kaynağını nuget.org
- Arama kutusuna "Swashbuckle.AspNetCore" yazın
- Browse sekmesinden Swashbuckle.AspNetCore paketini seçin ve Install (Kurulum) seçeneğine tıklayın
-
Swagger middleware ekle ve yapılandırÖnce isim alanını tanıtın: Swagger oluşturucusunu Startup.ConfigureServices metodunda hizmet koleksiyonuna ekleyin: daStartup.Configureyöntemini etkinleştirmek için oluşturulan JSON belgesine ve Swagger arayüzüne hizmet vermesini etkinleştirin:
Uygulamayı başlatın ve ona gidinhttps://localhost:<port>/swagger/v1/swagger.json。 Uç noktayı tanımlayan ortaya çıkan dokümantasyon JSON formatında aşağıdaki şekilde gösterilir.
Mevcuthttps://localhost:<port>/kendinden eminSwagger arayüzünü bul. Aşağıda gösterildiği gibi API dokümantasyonunu Swagger arayüzü üzerinden inceleyin.
Kökü uygulamak için (http://localhost:<port>/) Swagger arayüzü sağlamak için lütfenRoutePrefixÖzellik boş bir dizeye ayarlanmıştır:
Swagger'ın Gelişmiş Kullanımı (Özelleştirme ve Uzantılar)API dokümantasyonuna açıklayıcı bilgiler eklemek için Swagger kullanınAşağıdaki yapılandırma işlemleri, yazar, lisans ve açıklama bilgileri gibi bilgileri ekleyen AddSwaggerGen yöntemiyle gerçekleştirilir: Wagger UI ekran versiyonunun bilgileri aşağıdaki şekilde gösterilmiştir: Arayüz yöntemlerine yorum ekleyinÖnce API'ye tıklayalım, aşağıdaki şekilde gösterildiği gibi genişletelim, yorum olmaz mı, yorum nasıl eklenir? Aşağıdaki görselde gösterildiği gibi üç / olduğu gibi belge yorumlarını ekleyin Sonra projeyi çalıştırın ve swaggerUI'ye geri dönüp yorumun gelip görünmediğine bakın Hâlâ görünmedi, merak etme, aşağıya bak! XML açıklamalarını etkinleştirinAşağıdaki yöntemlerle XML açıklamalarını etkinleştirebilirsiniz: - Çözüm Gezginci'nde projeye sağ tıklayın ve Özellikler'i seçin
- Build sekmesinin Çıktı bölümünde XML Belge Dosyası kutusuna bakın
-
XML açıklamalarının etkinleştirilmesi, belgelenmemiş yaygın tipler ve üyeler için hata ayıklama bilgisi sağlar. Örneğin, çok sayıda uyarı mesajı görünürse, aşağıdaki mesaj uyarı kodu 1591'in ihlalini gösterir:
Ya OKB'niz varsa ve uyarıyı iptal etmek isterseniz? Aşağıdaki görselde gösterildiği gibi iptal edebilirsiniz
Yukarıda oluşturulan xml belge dosyasının yoluna dikkat edin,
Not: 1. Linux veya Windows dışı işletim sistemleri için, dosya isimleri ve yolları büyük harf duyarlıdır. Örneğin, bir "SwaggerDemo.xml" dosyası Windows'ta çalışır, ancak CentOS'ta çalışmaz. 2. Uygulama yolunu elde etmek için AppContext.BaseDirectory kullanılarak elde edilmesi önerilir Yeniden inşa edin ve yorumların gelip görünmediğini görmek için projeyi çalıştırın Yukarıdaki işlemden, Swagger arayüzünün <summary> yukarıdaki yorum kodundaki öğelerin iç metnini API büyük yorumlar olarak gösterdiği özetlenebilir! Elbette, açıklama öğesini de Alın nasıl yapılır dokümantasyonuna ekleyebilirsiniz. <summary> Öğede belirtilen bilgileri tamamlayabilir ve daha güvenilir bir Swagger arayüzü sağlayabilir. <remarks> Öğe içeriği metin, JSON veya XML içerebilir. Kod şöyledir: SwaggerUI kullanarak api arayüzünü test edinSwaggerUI üzerinden arayüzü küçük bir örnekle hata ayıklayalım
- Test edilmesi gereken API arayüzüne tıklayın ve ardından Parametrelerin sol ve sağındaki "Dene" butonuna tıklayın
- Aşağıdaki görselde gösterildiği gibi görünen parametre metin kutusuna bir parametre girin, parametre 2'yi girin
- Execute butonuna tıklayın, aşağıda gösterilen biçimlendirilmiş Yanıt görünecektir; aşağıdaki şekilde gösterildiği gibi.
İşte bugünkü Swagger ile Core WebApi'de API dokümantasyonu oluşturma eğitimi bu ASP.NET kadar. Umarım Swagger'ı kullanarak ASP.NET Core'da API dokümantasyonu oluşturmayı öğrenmeniz faydalı olur! özetBu makale, API dokümantasyonunu elle yazmanın acı noktasıyla başlıyor ve ardından otomatik olarak API dokümantasyonu oluşturan Swagger'a geçiyor! Ardından, kolay anlaşılır metin ve resimler aracılığıyla, SwaggerUI'nin ASP.NET Core WebApi'de API dokümantasyonu nasıl oluşturulacağını göstereceğiz. Son olarak, ASP.NET Core'da Swagger'ın bazı gelişmiş kullanımlarını tanıtacağım! Umarım ASP.NET Core'da Swagger'ı kullanmana yardımcı olur!
| 
Yayınlandı 12.04.2019 14:14:46
|
|
|
|
