NSwag ve ASP.NET Core kullanmaya başlama

Christoph Nienaber, Rico Suter ve Dave Brock tarafından

Örnek kodu görüntüleme veya indirme (indirme)

NSwag aşağıdaki özellikleri sunar:

• Swagger kullanıcı arabirimini ve Swagger oluşturucuyu kullanma olanağı.
• Esnek kod oluşturma özellikleri.

NSwag ile mevcut bir API'ye ihtiyacınız yoktur; Swagger'ı içeren ve bir istemci uygulaması oluşturan üçüncü taraf API'leri kullanabilirsiniz. NSwag, geliştirme döngüsünü hızlandırmanızı ve API değişikliklerine kolayca uyum sağlamanızı sağlar.

Paket yükleme

NSwag'ı şu şekilde yükleyin:

• Uygulanan web API'sinin Swagger belirtimini oluşturun.
• Web API'sine göz atmak ve test etmek için Swagger kullanıcı arabirimini sunma.
• Web API'sine API belgeleri eklemek için Redoc'a hizmet verme.

NSwag ASP.NET Core ara yazılımını kullanmak için NSwag.AspNetCore NuGet paketini yükleyin. Bu paket Swagger belirtimi, Swagger UI (v2 ve v3) ve ReDoc kullanıcı arabirimi oluşturmak ve sunmak için ara yazılımı içerir. NSwag 14, Swagger UI belirtiminin yalnızca v3'lerini destekler.

NSwag NuGet paketini yüklemek için aşağıdaki yaklaşımlardan birini kullanın:

Visual Studio

• Paket Yöneticisi Konsolu penceresinden:

  • Diğer Pencereleri> Görüntüle>Paket Yöneticisi Konsolu'na gidin

  • Dosyanın bulunduğu dizine NSwagSample.csproj gidin

  • Şu kodu yürütün:

    Install-Package NSwag.AspNetCore
    

• NuGet Paketlerini Yönet iletişim kutusundan:

  • Çözüm Gezgini> NuGet Paketlerini Yönet'te projeye sağ tıklayın
  • Paket kaynağını "nuget.org" olarak ayarlayın
  • Arama kutusuna "NSwag.AspNetCore" yazın
  • Gözat sekmesinden "NSwag.AspNetCore" paketini seçin ve Yükle'ye tıklayın

Mac için Visual Studio

• Çözüm Bölmesi>Paket Ekle'de Paketler klasörüne sağ tıklayın...
• Paket Ekle penceresinin Kaynak açılan menüsünü "nuget.org" olarak ayarlayın
• Arama kutusuna "NSwag.AspNetCore" yazın
• Sonuçlar bölmesinden "NSwag.AspNetCore" paketini seçin ve Paket Ekle'ye tıklayın

Visual Studio Code

Tümleşik Terminal'den aşağıdaki komutu çalıştırın:

dotnet add NSwagSample.csproj package NSwag.AspNetCore

.NET CLI

Şu komutu çalıştırın:

dotnet add NSwagSample.csproj package NSwag.AspNetCore

Swagger ara yazılımı ekleme ve yapılandırma

Aşağıdaki adımları uygulayarak ASP.NET Core uygulamanıza Swagger ekleyin ve yapılandırın:

• Içindeki hizmetler koleksiyonuna Program.csOpenApi oluşturucuyu ekleyin:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddOpenApiDocument();

• Oluşturulan OpenApi belirtimini, Swagger kullanıcı arabirimini ve Redoc kullanıcı arabirimini de içinde Program.cskullanıma açmak için ara yazılımı etkinleştirin:

if (app.Environment.IsDevelopment())
{
    // Add OpenAPI 3.0 document serving middleware
    // Available at: http://localhost:<port>/swagger/v1/swagger.json
    app.UseOpenApi();

    // Add web UIs to interact with the document
    // Available at: http://localhost:<port>/swagger
    app.UseSwaggerUi(); // UseSwaggerUI Protected by if (env.IsDevelopment())
}

• Uygulamayı başlatma. Şu sayfaya gidin:
  • http://localhost:<port>/swagger Swagger kullanıcı arabirimini görüntülemek için.
  • http://localhost:<port>/swagger/v1/swagger.json Swagger belirtimini görüntülemek için.

Kod oluşturma

Aşağıdaki seçeneklerden birini belirleyerek NSwag'ın kod oluşturma özelliklerinden yararlanabilirsiniz:

• NSwagStudio: C# veya TypeScript'te API istemci kodu oluşturmaya yönelik bir Windows masaüstü uygulaması.
• Projenizde kod oluşturma için NSwag.CodeGeneration.CSharp veya NSwag.CodeGeneration.TypeScript NuGet paketleri.
• Komut satırından NSwag.
• NSwag.MSBuild NuGet paketi.
• OpenAPI (Swagger) Bağlı Hizmetini Açma: C# veya TypeScript'te API istemci kodu oluşturmak için Visual Studio Bağlı Hizmeti. Ayrıca NSwag ile OpenAPI hizmetleri için C# denetleyicileri oluşturur.

NSwagStudio ile kod oluşturma

• NSwagStudio GitHub deposundaki yönergeleri izleyerek NSwagStudio'yu yükleyin. NSwag yayın sayfasında, yükleme ve yönetici ayrıcalıkları olmadan başlatabileceğiniz bir xcopy sürümü indirebilirsiniz.
• NSwagStudio'yi başlatın ve Swagger Belirtimi URL'si metin kutusuna dosya URL'sini girinswagger.json. Örneğin, http://localhost:5232/swagger/v1/swagger.json.
• Swagger belirtiminizin JSON gösterimini oluşturmak için Yerel Kopya Oluştur düğmesine tıklayın.

• Çıkışlar alanında CSharp İstemcisi onay kutusuna tıklayın. Projenize bağlı olarak, TypeScript İstemcisi veya CSharp Web API Denetleyicisi'ni de seçebilirsiniz. CSharp Web API Denetleyicisi'ni seçerseniz, hizmet belirtimi hizmeti yeniden oluşturur ve ters oluşturma görevi görür.
• TodoApi.NSwag projesinin tam bir C# istemci uygulamasını oluşturmak için Çıkış Oluştur'a tıklayın. Oluşturulan istemci kodunu görmek için CSharp İstemcisi sekmesine tıklayın:

namespace MyNamespace
{
    using System = global::System;

    [System.CodeDom.Compiler.GeneratedCode("NSwag", "14.0.1.0 (NJsonSchema v11.0.0.0 (Newtonsoft.Json v13.0.0.0))")]
    public partial class TodoClient
    {
    #pragma warning disable 8618 // Set by constructor via BaseUrl property
        private string _baseUrl;
    #pragma warning restore 8618 // Set by constructor via BaseUrl property
        private System.Net.Http.HttpClient _httpClient;
        private static System.Lazy<Newtonsoft.Json.JsonSerializerSettings> _settings = new System.Lazy<Newtonsoft.Json.JsonSerializerSettings>(CreateSerializerSettings, true);

        public TodoClient(System.Net.Http.HttpClient httpClient)
        {
            BaseUrl = "http://localhost:5232";
            _httpClient = httpClient;
        }

        private static Newtonsoft.Json.JsonSerializerSettings CreateSerializerSettings()
        {
            var settings = new Newtonsoft.Json.JsonSerializerSettings();
            UpdateJsonSerializerSettings(settings);
            return settings;
        }

        public string BaseUrl
        {
            get { return _baseUrl; }
            set
            {
                _baseUrl = value;
                if (!string.IsNullOrEmpty(_baseUrl) && !_baseUrl.EndsWith("/"))
                    _baseUrl += '/';
            }
        }
        // code omitted for brevity

İpucu

C# istemci kodu, Ayarlar sekmesindeki seçimlere göre oluşturulur. Varsayılan ad alanı yeniden adlandırma ve zaman uyumlu yöntem oluşturma gibi görevleri gerçekleştirmek için ayarları değiştirin.

• Oluşturulan C# kodunu, API'yi kullanacak istemci projesindeki bir dosyaya kopyalayın.
• Web API'sini kullanmaya başlayın:

var todoClient = new TodoClient(new HttpClient());

// Gets all to-dos from the API
var allTodos = await todoClient.GetAsync();

// Create a new TodoItem, and save it via the API.
await todoClient.CreateAsync(new TodoItem());

// Get a single to-do by ID
var foundTodo = await todoClient.GetByIdAsync(1);

API belgelerini özelleştirme

OpenApi, web API'sinin tüketimini kolaylaştırmak için nesne modelini belgeleme seçenekleri sağlar.

API bilgileri ve açıklaması

içinde Program.cs, Web API'sinin belge bilgilerini yapılandıracak ve yazar, lisans ve açıklama gibi daha fazla bilgi içerecek şekilde güncelleştirin AddOpenApiDocument . NSwag Sınıfları kullanmak için önce ad alanını içeri aktarınOpenApi.

using NSwag;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApiDocument(options => {
     options.PostProcess = document =>
     {
         document.Info = new OpenApiInfo
         {
             Version = "v1",
             Title = "ToDo API",
             Description = "An ASP.NET Core Web API for managing ToDo items",
             TermsOfService = "https://example.com/terms",
             Contact = new OpenApiContact
             {
                 Name = "Example Contact",
                 Url = "https://example.com/contact"
             },
             License = new OpenApiLicense
             {
                 Name = "Example License",
                 Url = "https://example.com/license"
             }
         };
     };
});

Swagger kullanıcı arabirimi sürümün bilgilerini görüntüler:

XML açıklamaları

XML açıklamalarını etkinleştirmek için aşağıdaki adımları uygulayın:

Visual Studio

• Çözüm Gezgini'da projeye sağ tıklayın ve öğesini seçinEdit <project_name>.csproj.
• Vurgulanan satırları dosyaya .csproj el ile ekleyin:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

Mac için Visual Studio

• Çözüm Bölmesi'nden denetime basın ve proje adına tıklayın. Araçlar>Dosya Düzenle'ye gidin.
• Vurgulanan satırları dosyaya .csproj el ile ekleyin:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

Visual Studio Code

Vurgulanan satırları dosyaya .csproj el ile ekleyin:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

.NET CLI

Vurgulanan satırları dosyaya .csproj el ile ekleyin:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

XML açıklamalarının etkinleştirilmesi, belgelenmemiş genel türler ve üyeler için hata ayıklama bilgileri sağlar. Belgelenmemiş türler ve üyeler uyarı iletisiyle gösterilir. Örneğin, aşağıdaki ileti uyarı kodu 1591'in ihlalini gösterir:

warning CS1591: Missing XML comment for publicly visible type or member 'TodoContext'

Proje genelinde uyarıları engellemek için proje dosyasında yoksaymak üzere noktalı virgülle ayrılmış bir uyarı kodu listesi tanımlayın. Uyarı kodlarının eklenmesi $(NoWarn); C# varsayılan değerlerini de uygular.

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

Yalnızca belirli üyelere yönelik uyarıları engellemek için kodu #pragma uyarı önişlemci yönergeleri içine alın. Bu yaklaşım, API belgeleri aracılığıyla kullanıma sunulmaması gereken kodlar için kullanışlıdır. Aşağıdaki örnekte, cs1591 uyarı kodu sınıfın tamamı TodoContext için yoksayılır. Uyarı kodunun uygulanması, sınıf tanımının kapanışında geri yüklenir. Virgülle ayrılmış bir listeyle birden çok uyarı kodu belirtin.

namespace NSwagSample.Models;

#pragma warning disable CS1591
public class TodoContext : DbContext
{
    public TodoContext(DbContextOptions<TodoContext> options) : base(options) { }

    public DbSet<TodoItem> TodoItems => Set<TodoItem>();
}
#pragma warning restore CS1591

Veri açıklamaları

Swagger KULLANıCı arabirimi bileşenlerinin sürücüye yardımcı olması için modeli ad alanında System.ComponentModel.DataAnnotations bulunan özniteliklerle işaretleyin.

özniteliğini [Required] Name sınıfının özelliğine TodoItem ekleyin:

using System.ComponentModel;
using System.ComponentModel.DataAnnotations;

namespace NSwagSample.Models;

public class TodoItem
{
    public long Id { get; set; }

    [Required]
    public string Name { get; set; } = null!;

    [DefaultValue(false)]
    public bool IsComplete { get; set; }
}

Bu özniteliğin varlığı kullanıcı arabirimi davranışını değiştirir ve temel alınan JSON şemasını değiştirir:

"TodoItem": {
  "type": "object",
  "additionalProperties": false,
  "required": [
    "name"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "format": "int64"
    },
    "name": {
      "type": "string",
      "minLength": 1
    },
    "isComplete": {
      "type": "boolean",
      "default": false
    }
  }
}

Web API'sinde veri ek açıklamalarının kullanımı arttıkça, kullanıcı arabirimi ve API yardım sayfaları daha açıklayıcı ve kullanışlı hale gelir.

Yanıt türlerini açıklama

Web API'sini kullanan geliştiriciler, özellikle yanıt türleri ve hata kodları (standart değilse) olmak üzere döndürülen öğelerle ilgilenir. Yanıt türleri ve hata kodları XML açıklamalarında ve veri ek açıklamalarında belirtilir.

Eylem, Create başarılı olduğunda bir HTTP 201 durum kodu döndürür. Gönderilen istek gövdesi nullolduğunda bir HTTP 400 durum kodu döndürülür. Swagger kullanıcı arabiriminde uygun belgeler olmadan, tüketici bu beklenen sonuçlar hakkında bilgi sahibi değildir. Aşağıdaki örnekte vurgulanan satırları ekleyerek bu sorunu düzeltin:

/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item #1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <response code="201">Returns the newly created item</response>
/// <response code="400">If the item is null</response>
[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<IActionResult> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    await _context.SaveChangesAsync();

    return CreatedAtAction(nameof(Get), new { id = item.Id }, item);
}

Swagger kullanıcı arabirimi artık beklenen HTTP yanıt kodlarını açıkça belgelemektedir (ve XML açıklamaları da görüntülenir):

Kurallar, ile [ProducesResponseType]tek tek eylemleri açıkça dekore etmek için alternatif olarak kullanılabilir. Daha fazla bilgi için bkz . Web API kurallarını kullanma.

Redoc

Redoc, Swagger kullanıcı arabirimine bir alternatiftir. Benzerdir çünkü OpenAPI belirtimini kullanarak Web API'si için bir belge sayfası da sağlar. Fark, Redoc kullanıcı arabiriminin belgelere daha fazla odaklanması ve API'yi test etmek için etkileşimli bir kullanıcı arabirimi sağlamamasıdır.

Redoc'i etkinleştirmek için ara yazılımını öğesine Program.csekleyin:

if (app.Environment.IsDevelopment())
{
    // Add OpenAPI 3.0 document serving middleware
    // Available at: http://localhost:<port>/swagger/v1/swagger.json
    app.UseOpenApi();

    // Add web UIs to interact with the document
    // Available at: http://localhost:<port>/swagger
    app.UseSwaggerUi(); // UseSwaggerUI is called only in Development.
    
    // Add ReDoc UI to interact with the document
    // Available at: http://localhost:<port>/redoc
    app.UseReDoc(options =>
    {
        options.Path = "/redoc";
    });
}

Uygulamayı çalıştırın ve Redoc kullanıcı arabirimini görüntülemek için adresine gidin http://localhost:<port>/redoc :