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:

dotnet add NSwagSample.csproj package NSwag.AspNetCore

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

• 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:

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

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

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

<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 :

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.

NSwag ara yazılımını kaydetme

NSwag ara yazılımını şu şekilde kaydedin:

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

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 NuGet paketini yüklemek için aşağıdaki yaklaşımlardan birini kullanın:

dotnet add TodoApi.csproj package NSwag.AspNetCore

dotnet add TodoApi.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:

• yönteminde Startup.ConfigureServices gerekli Swagger hizmetlerini kaydedin:

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt =>
        opt.UseInMemoryDatabase("TodoList"));
    services.AddMvc();

    // Register the Swagger services
    services.AddSwaggerDocument();
}

• yönteminde Startup.Configure , oluşturulan Swagger belirtimini ve Swagger kullanıcı arabirimini sağlamak için ara yazılımı etkinleştirin:

public void Configure(IApplicationBuilder app)
{
    app.UseStaticFiles();

    // Register the Swagger generator and the Swagger UI middlewares
    app.UseOpenApi();
    app.UseOpenApi();
    if (env.IsDevelopment())
    {
        app.UseSwaggerUi3();
    }
    app.UseMvc();
}

• 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:44354/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:

//----------------------
// <auto-generated>
//     Generated using the NSwag toolchain v12.0.9.0 (NJsonSchema v9.13.10.0 (Newtonsoft.Json v11.0.0.0)) (http://NSwag.org)
// </auto-generated>
//----------------------

namespace MyNamespace
{
    #pragma warning disable

    [System.CodeDom.Compiler.GeneratedCode("NSwag", "12.0.9.0 (NJsonSchema v9.13.10.0 (Newtonsoft.Json v11.0.0.0))")]
    public partial class TodoClient
    {
        private string _baseUrl = "https://localhost:44354";
        private System.Net.Http.HttpClient _httpClient;
        private System.Lazy<Newtonsoft.Json.JsonSerializerSettings> _settings;

        public TodoClient(System.Net.Http.HttpClient httpClient)
        {
            _httpClient = httpClient;
            _settings = new System.Lazy<Newtonsoft.Json.JsonSerializerSettings>(() =>
            {
                var settings = new Newtonsoft.Json.JsonSerializerSettings();
                UpdateJsonSerializerSettings(settings);
                return settings;
            });
        }

        public string BaseUrl
        {
            get { return _baseUrl; }
            set { _baseUrl = value; }
        }

        // code omitted for brevity

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

 var todoClient = new TodoClient();

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

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

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

API belgelerini özelleştirme

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

API bilgileri ve açıklaması

yönteminde Startup.ConfigureServices , yöntemine AddSwaggerDocument geçirilen bir yapılandırma eylemi yazar, lisans ve açıklama gibi bilgileri ekler:

services.AddSwaggerDocument(config =>
{
    config.PostProcess = document =>
    {
        document.Info.Version = "v1";
        document.Info.Title = "ToDo API";
        document.Info.Description = "A simple ASP.NET Core web API";
        document.Info.TermsOfService = "None";
        document.Info.Contact = new NSwag.OpenApiContact
        {
            Name = "Shayne Boyer",
            Email = string.Empty,
            Url = "https://twitter.com/spboyer"
        };
        document.Info.License = new NSwag.OpenApiLicense
        {
            Name = "Use under LICX",
            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:

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

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

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

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

Veri açıklamaları

NSwag Yansıma kullandığından ve web API eylemleri için önerilen dönüş türü ActionResult<T> olduğundan, yalnızca tarafından Ttanımlanan dönüş türünü çıkarsayabilir. Diğer olası dönüş türlerini otomatik olarak çıkaramazsınız.

Aşağıdaki örneği inceleyin:

[HttpPost]
public ActionResult<TodoItem> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    _context.SaveChanges();

    return CreatedAtRoute("GetTodo", new { id = item.Id }, item);
}

Önceki eylem döndürür ActionResult<T>. Eylemin içinde döndürür CreatedAtRoute. Denetleyici özniteliğine [ApiController] sahip olduğundan, bir BadRequest yanıt da mümkündür. Daha fazla bilgi için bkz . Otomatik HTTP 400 yanıtları. İstemcilere bu eylemin döndüreceği bilinen HTTP durum kodlarını bildirmek için veri ek açıklamalarını kullanın. Eylemi aşağıdaki özniteliklerle işaretleyin:

[ProducesResponseType(StatusCodes.Status201Created)]     // Created
[ProducesResponseType(StatusCodes.Status400BadRequest)]  // BadRequest

ASP.NET Core 2.2 veya sonraki sürümlerinde, ile [ProducesResponseType]tek tek eylemleri açıkça süslemek yerine kuralları kullanabilirsiniz. Daha fazla bilgi için bkz . Web API kurallarını kullanma.

Swagger oluşturucu artık bu eylemi doğru şekilde açıklayabilir ve oluşturulan istemciler uç noktayı çağırırken ne aldıklarını bilir. Öneri olarak, tüm eylemleri bu özniteliklerle işaretleyin.

API eylemlerinizin döndürmesi gereken HTTP yanıtlarıyla ilgili yönergeler için bkz . RFC 9110: HTTP Semantiği (Bölüm 9.3). Yöntem Tanımları).