Kullanmaya başlayın NSwag ve ASP.NET Core

Ophoph Uternaber, Riko Suterve Dave Brock tarafından

NSwag aşağıdaki özellikleri sunar:

• Swagger UI ve Swagger oluşturucu kullanma özelliği.
• Esnek kod oluşturma özellikleri.

NSwag ile var olan bir API'ye ihtiyacınız yok. Swagger'ı içeren üçüncü taraf API'leri kullanabilir ve — bir istemci uygulaması oluşturabilirsiniz. NSwag, geliştirme döngüsünü hızlandırmaya ve API değişikliklerine kolayca uyum sağlamaya olanak sağlar.

NSwag ara yazılımlarını kaydetme

NSwag ara yazılımlarını kaydetmek için:

• Uygulanan web API'si için Swagger belirtimi oluşturma.
• Web API'sine göz atmak ve test etmek için Swagger kullanıcı arabirimine hizmet edin.

NSwag ASP.NET Core kullanmak için NSwag.AspNetCore NuGet yükleyin. Bu paket Swagger belirtimi, Swagger UI (v2 ve v3) ve ReDockullanıcı arabirimi oluşturmak ve hizmet vermek için ara yazılımı içerir.

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

dotnet add TodoApi.csproj package NSwag.AspNetCore

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

Aşağıdaki adımları gerçekleştirerek Swagger'ı ASP.NET Core uygulamanıza ekleyin ve yapılandırabilirsiniz:

• Startup.ConfigureServicesyönteminde, gerekli Swagger hizmetlerini kaydettirin:

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

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

• Startup.Configureyönteminde, oluşturulan Swagger belirtimini ve Swagger kullanıcı arabirimini sunan 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.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 seçerek NSwag'ın kod oluşturma özelliklerine sahip olabilirsiniz:

• NSwagStudio:C# Windows TypeScript'te API istemci kodu oluşturmak için bir masaüstü uygulamasıdır.
• NSwag.CodeGeneration.CSharp veya NSwag.CodeGeneration.TypeScript NuGet projenizin içinde kod oluşturma paketleri içerir.
• Komut satırına NSwag yazın.
• NSwag.MSBuild NuGet paketi.
• OpenAPI (Swagger)Bağlı Hizmetinin SatınSınırla: C# Visual Studio TypeScript'te API istemci kodu oluşturmak için bir Bağlı Hizmettir. Ayrıca NSwag ile OpenAPI hizmetleri için C# denetleyicileri de üretir.

NSwagStudio ile kod oluşturma

• NSwagStudio'yu yüklemek için NSwagStudio deposundaki yönergeleri GitHub yükleyin. NSwag yayın sayfasında, yükleme ve yönetici ayrıcalıkları olmadan başlatabilirsiniz bir xcopy sürümünü indirebilirsiniz.

• NSwagStudio'yu açın ve Swagger Belirtimi URL'si metin kutusunaswagger.jsURL'sini girin. Ö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'ne de seçebilirsiniz. CSharp Web API Controller'ı seçersiniz, hizmet belirtimi hizmeti yeniden oluşturur ve ters nesil olarak görev gösterir.

• 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 tüketecek istemci projesinde bir dosyaya kopyalayın.
• Web API'sini tüketerek başlama:

 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'si tüketimini kolaylaştırmak için nesne modelini belgeleye seçenekler sağlar.

API bilgileri ve açıklaması

Startup.ConfigureServicesyönteminde, yöntemine geçirilen bir yapılandırma AddSwaggerDocument eylemi yazar, lisans ve açıklama gibi bilgiler 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 UI 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ı gerçekleştirin:

<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>
  <DocumentationFile>bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml</DocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

Veri açıklamaları

[HttpPost]
public IActionResult Create([FromBody] TodoItem item)
{
    if (item == null)
    {
        return BadRequest();
    }

    _context.TodoItems.Add(item);
    _context.SaveChanges();

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

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

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

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

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

Swagger Oluşturucusu artık bu eylemi doğru bir şekilde tanımlayabilir ve üretilen istemciler, uç noktayı çağırırken ne elde ettikleri hakkında bilgi alabilir. Öneri olarak tüm eylemleri bu özniteliklerle işaretleyin.

API eylemlerinizin dönmesi gereken HTTP yanıtlarının hakkında yönergeler için bkz. RFC 7231 belirtimi.