Nguon: Microsoft Learn · .NET 8.0

Bắt đầu với NSwag và ASP.NET Core

Nguồn: Get started with NSwag and ASP.NET Core

Bởi Rico Suter và Dave Brock

NSwag cung cấp các khả năng sau:

Với NSwag, bạn không cần có API sẵn — bạn có thể sử dụng API của bên thứ ba tích hợp Swagger và tạo triển khai client. NSwag cho phép bạn tăng tốc chu kỳ phát triển và dễ dàng thích ứng với các thay đổi API.

Cài đặt package

Cài đặt NSwag để:

Để sử dụng middleware NSwag cho ASP.NET Core, cài đặt package NuGet NSwag.AspNetCore. Package này chứa middleware để tạo và phục vụ đặc tả Swagger, Swagger UI (v2 và v3), và ReDoc UI. NSwag 14 chỉ hỗ trợ v3 của đặc tả Swagger UI.

Sử dụng một trong các cách sau để cài đặt package NuGet NSwag:

Visual Studio

``powershell Install-Package NSwag.AspNetCore ``

Visual Studio Code

Chạy lệnh sau từ Integrated Terminal:

dotnetcli
dotnet add NSwagSample.csproj package NSwag.AspNetCore

.NET CLI

Chạy lệnh sau:

dotnetcli
dotnet add NSwagSample.csproj package NSwag.AspNetCore

Thêm và cấu hình Swagger middleware

Thêm và cấu hình Swagger trong ứng dụng ASP.NET Core của bạn bằng cách thực hiện các bước sau:

csharp
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddOpenApiDocument();
csharp
if (app.Environment.IsDevelopment())
{
    // Thêm middleware phục vụ tài liệu OpenAPI 3.0
    // Có tại: http://localhost:<port>/swagger/v1/swagger.json
    app.UseOpenApi();

    // Thêm web UI để tương tác với tài liệu
    // Có tại: http://localhost:<port>/swagger
    app.UseSwaggerUi(); // UseSwaggerUI chỉ được gọi trong Development.
}

Sinh code (Code generation)

Bạn có thể tận dụng các khả năng sinh code của NSwag bằng cách chọn một trong các tùy chọn sau:

Sinh code với NSwagStudio

csharp
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;
        }

        // code được lược bỏ cho ngắn gọn

Mẹo: Code C# client được tạo dựa trên các lựa chọn trong tab Settings. Sửa đổi cài đặt để thực hiện các tác vụ như đổi tên namespace mặc định và tạo phương thức đồng bộ.

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

// Lấy tất cả to-do từ API
var allTodos = await todoClient.GetAsync();

// Tạo TodoItem mới và lưu qua API.
await todoClient.CreateAsync(new TodoItem());

// Lấy một to-do theo ID
var foundTodo = await todoClient.GetByIdAsync(1);

Tùy chỉnh tài liệu API

OpenApi cung cấp các tùy chọn để tài liệu hóa object model nhằm dễ dàng sử dụng web API.

Thông tin và mô tả API

Trong Program.cs, cập nhật AddOpenApiDocument để cấu hình thông tin tài liệu của Web API và bao gồm thêm thông tin như tác giả, giấy phép và mô tả. Import namespace NSwag trước tiên để sử dụng các lớp OpenApi:

csharp
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"
             }
         };
     };
});

Comment XML (XML comments)

Để kích hoạt comment XML, thực hiện các bước sau. Thêm GenerateDocumentationFile vào file .csproj:

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

Để bỏ qua cảnh báo trên toàn dự án:

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

Để bỏ qua cảnh báo chỉ cho các thành viên cụ thể, bao quanh code bằng chỉ thị tiền xử lý #pragma warning:

csharp
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

Data annotations (chú thích dữ liệu)

Đánh dấu model bằng các attribute trong namespace System.ComponentModel.DataAnnotations để giúp điều khiển các thành phần Swagger UI.

Thêm attribute [Required] vào thuộc tính Name của lớp TodoItem:

csharp
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; }
}

Khi sử dụng data annotation trong web API ngày càng nhiều, UI và các trang trợ giúp API trở nên mô tả đầy đủ và hữu ích hơn.

Mô tả kiểu response

Thêm các dòng được đánh dấu để tài liệu hóa các HTTP response code mong đợi:

csharp
/// <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);
}

Convention (quy ước) có thể được dùng thay thế để tránh phải trang trí thủ công từng action với [ProducesResponseType]. Để biết thêm thông tin, xem Sử dụng web API conventions.

Redoc

Redoc là một giải pháp thay thế cho Swagger UI. Nó tương tự vì cũng cung cấp trang tài liệu cho Web API sử dụng đặc tả OpenAPI. Sự khác biệt là Redoc UI tập trung hơn vào tài liệu và không cung cấp UI tương tác để kiểm thử API.

Để kích hoạt Redoc, thêm middleware của nó vào Program.cs:

csharp
if (app.Environment.IsDevelopment())
{
    // Thêm middleware phục vụ tài liệu OpenAPI 3.0
    // Có tại: http://localhost:<port>/swagger/v1/swagger.json
    app.UseOpenApi();

    // Thêm web UI để tương tác với tài liệu
    // Có tại: http://localhost:<port>/swagger
    app.UseSwaggerUi(); // UseSwaggerUI chỉ được gọi trong Development.
    
    // Thêm ReDoc UI để tương tác với tài liệu
    // Có tại: http://localhost:<port>/redoc
    app.UseReDoc(options =>
    {
        options.Path = "/redoc";
    });
}

Chạy ứng dụng và điều hướng đến http://localhost:<port>/redoc để xem Redoc UI.