Az NSwag és a ASP.NET Core használatának első lépései

Rico Suter és Dave Brock

Mintakód megtekintése vagy letöltése (hogyan töltsd le)

Az NSwag a következő képességeket kínálja:

• A Swagger felhasználói felületének és a Swagger generátornak a használata.
• Rugalmas kódgenerálási képességek.

Az NSwag használatával nincs szükség meglévő API-ra – használhat olyan külső API-kat, amelyek swaggert tartalmaznak, és létrehoznak egy ügyfél-implementációt. Az NSwag lehetővé teszi a fejlesztési ciklus felgyorsítását és az API-módosításokhoz való könnyű alkalmazkodást.

Csomag telepítése

Telepítse az NSwagot:

• Hozza létre a Swagger specifikációját a implementált webes API-hoz.
• A Swagger felhasználói felületének kiszolgálása a webes API böngészéséhez és teszteléséhez.
• A Redoc szolgáltatásával api-dokumentációt adhat hozzá a webes API-hoz.

Az NSwag ASP.NET Core köztes szoftver használatához telepítse az NSwag.AspNetCore NuGet csomagot. Ez a csomag tartalmazza a köztes szoftvert, amely létrehozza és kiszolgálja a Swagger specifikációját, a Swagger felhasználói felületét (v2 és v3) és a ReDoc felhasználói felületét. Az NSwag 14 csak a Swagger felhasználói felületének 3-as verziójára vonatkozik.

Az NSwag NuGet-csomag telepítéséhez használja az alábbi módszerek egyikét:

Visual Studio

• A Package Manager konzol ablakából:

  • Tekintse meg Nézet>Egyéb ablakok>Csomagkezelő konzol

  • Lépjen arra a könyvtárra, amelyben a NSwagSample.csproj fájl létezik

  • Hajtsa végre a következő parancsot:

    Install-Package NSwag.AspNetCore
    

• A NuGet-csomagok kezelése ablakban:

  • Kattintson a jobb gombbal a projektre Megoldáskezelőben>NuGet-csomagok kezelése
  • A csomag forrásának beállítása "nuget.org" értékre
  • Írja be az "NSwag.AspNetCore" kifejezést a keresőmezőbe
  • Válassza ki az "NSwag.AspNetCore" csomagot a Tallózás lapon, és kattintson a Telepítés gombra

Visual Studio for Mac

• Kattintson a jobb gombbal a Csomagok mappára Megoldáspanel>Csomagok hozzáadása...
• Állítsa a Csomagok hozzáadása ablak Forrás legördülő menüt "nuget.org" értékre
• Írja be az "NSwag.AspNetCore" kifejezést a keresőmezőbe
• Válassza ki az "NSwag.AspNetCore" csomagot az eredménypanelen, és kattintson a Csomag hozzáadása elemre

Visual Studio Code

Futtassa a következő parancsot az integrált terminálból:

dotnet add NSwagSample.csproj package NSwag.AspNetCore

.NET CLI

Futtassa a következő parancsot:

dotnet add NSwagSample.csproj package NSwag.AspNetCore

Swagger köztes szoftver hozzáadása és konfigurálása

Adja hozzá és konfigurálja a Swaggert a ASP.NET Core-alkalmazásban az alábbi lépések végrehajtásával:

• Adja hozzá az OpenApi-generátort a következő szolgáltatásgyűjteményhez Program.cs:

var builder = WebApplication.CreateBuilder(args);

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

• Engedélyezze a köztes szoftver futtatását a létrehozott OpenApi-specifikáció, a Swagger UI és a Redoc UI kiszolgálásához, a következőben is: Program.cs

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())
}

• Indítsa el az alkalmazást. Navigáljon a következőhöz:
  • http://localhost:<port>/swagger A Swagger felhasználói felületének megtekintéséhez.
  • http://localhost:<port>/swagger/v1/swagger.json a Swagger specifikációjának megtekintéséhez.

Kódgenerálás

Az NSwag kódgenerálási képességei az alábbi lehetőségek egyikének kiválasztásával használhatók:

• NSwagStudio: Asztali Windows-alkalmazás API-ügyfélkód C# vagy TypeScript nyelven történő létrehozásához.
• Az NSwag.CodeGeneration.CSharp vagy NSwag.CodeGeneration.TypeScript NuGet-csomagok a projekten belüli kódgeneráláshoz.
• NSwag a parancssorból.
• Az NSwag.MSBuild NuGet csomag.
• Az Unchase OpenAPI (Swagger) Connected Service: Visual Studio Connected Service az API-ügyfélkód C# vagy TypeScript nyelven történő létrehozásához. Emellett C#-vezérlőket is létrehoz az OpenAPI-szolgáltatásokhoz az NSwag használatával.

Kód létrehozása az NSwagStudio használatával

• Telepítse az NSwagStudio-t az NSwagStudio GitHub-adattár utasításait követve. Az NSwag kiadási oldalán letölthet egy xcopy-verziót, amely telepítés és rendszergazdai jogosultságok nélkül indítható el.
• Indítsa el az NSwagStudio fájlt, és írja be a swagger.json fájl URL-címét a Swagger Specifikáció URL-címének szövegmezőjébe. Például: http://localhost:5232/swagger/v1/swagger.json.
• Kattintson a Helyi másolás létrehozása gombra a Swagger-specifikáció JSON-ábrázolásának létrehozásához.

• A Kimenetek területen kattintson a CSharp-ügyfél jelölőnégyzetére. A projekttől függően a TypeScript-ügyfél vagy a CSharp webes API-vezérlőt is választhatja. Ha a CSharp Web API Controllert választja, a szolgáltatás specifikációja újraépíti a szolgáltatást, és fordított generációként szolgál.
• Kattintson a Kimenetek létrehozása elemre a TodoApi.NSwag projekt teljes C#-ügyfél-implementációjának létrehozásához. A létrehozott ügyfélkód megtekintéséhez kattintson a CSharp-ügyfél fülre:

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

Jótanács

A C#-ügyfélkód a Beállítások lap beállításai alapján jön létre. Módosítsa a beállításokat olyan feladatok végrehajtásához, mint az alapértelmezett névtér átnevezése és a szinkron metódus létrehozása.

• Másolja a létrehozott C#-kódot az API-t használó ügyfélprojekt egyik fájljába.
• Kezdje el a webes API használatát:

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-dokumentáció testreszabása

Az OpenApi lehetővé teszi az objektummodell dokumentálását, hogy megkönnyítse a webes API használatát.

API-információk és leírás

A Program.cs esetén frissítse a AddOpenApiDocument-t a webes API dokumentumadatainak konfigurálásához, és adjon meg további információkat, például a szerzőt, a licencet és a leírást. Először importálja a NSwag névteret az OpenApi osztályok használatához.

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

A Swagger felhasználói felülete megjeleníti a verzió adatait:

XML-megjegyzések

Xml-megjegyzések engedélyezéséhez hajtsa végre a következő lépéseket:

Visual Studio

• Kattintson a jobb gombbal a projektre Megoldáskezelő, és válassza a Edit <project_name>.csprojlehetőséget.
• Adja hozzá manuálisan a kiemelt sorokat a .csproj fájlhoz:

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

Visual Studio for Mac

• A megoldáspanel-ről nyomja meg a vezérlőt, majd kattintson a projekt nevére. Lépjen Eszközök>Fájl szerkesztéseelemre.
• Adja hozzá manuálisan a kiemelt sorokat a .csproj fájlhoz:

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

Visual Studio Code

Adja hozzá manuálisan a kiemelt sorokat a .csproj fájlhoz:

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

.NET CLI

Adja hozzá manuálisan a kiemelt sorokat a .csproj fájlhoz:

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

Az XML-megjegyzések engedélyezése hibakeresési információkat biztosít a nem dokumentált nyilvános típusok és tagok számára. A nem dokumentált típusokat és tagokat a figyelmeztető üzenet jelzi. Az alábbi üzenet például az 1591-ben megjelenő figyelmeztető kód megsértését jelzi:

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

A projektszintű figyelmeztetések mellőzéséhez definiálja a projektfájlban figyelmen kívül hagyandó figyelmeztető kódok pontosvesszővel tagolt listáját. Ha hozzáfűzi a figyelmeztetési kódokat a $(NoWarn);-hoz, akkor a C# alapértelmezett értékei is alkalmazásra kerülnek-ben.

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

Ha csak bizonyos tagok figyelmeztetéseit szeretné letiltani, a kódot #pragma figyelmeztetési előfeldolgozási irányelvekbe kell belefoglalnia. Ez a módszer olyan kódok esetében hasznos, amelyeket nem szabad az API-dokumentumokon keresztül elérhetővé tenni. Az alábbi példában a CS1591 figyelmeztető kód figyelmen kívül lesz hagyva a teljes TodoContext osztályban. A figyelmeztető kód érvényesítése az osztálydefiníció végén lesz visszaállítva. Adjon meg több figyelmeztető kódot vesszővel tagolt listával.

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

Adatjegyzetek

Jelölje meg a modellt a System.ComponentModel.DataAnnotations névtérben található attribútumokkal, hogy segítsen a Swagger felhasználói felület összetevőinek meghajtásában.

Adja hozzá a [Required] attribútumot a Name osztály TodoItem tulajdonságához:

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

Az attribútum jelenléte megváltoztatja a felhasználói felület viselkedését, és módosítja a mögöttes JSON-sémát:

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

A webes API-ban az adatjegyzetek használatának növekedésével a felhasználói felület és az API súgóoldalai leíróbbá és hasznosabbá válnak.

Választípusok leírása

A webes API-t használó fejlesztők leginkább a visszaadott adatokkal foglalkoznak, különösen a választípusokkal és a hibakódokkal (ha nem standard). A választípusok és hibakódok az XML-megjegyzésekben és az adatjegyzetekben jelennek meg.

A Create művelet sikeres végrehajtás esetén egy HTTP 201 állapotkódot ad vissza. A rendszer HTTP 400-állapotkódot ad vissza, amikor a közzétett kérelem törzse null. A Swagger felhasználói felületén található megfelelő dokumentáció nélkül a fogyasztó nem ismeri ezeket a várt eredményeket. A probléma megoldásához adja hozzá a kiemelt sorokat az alábbi példában:

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

A Swagger felhasználói felülete mostantól egyértelműen dokumentálja a várt HTTP-válaszkódokat (és az XML-megjegyzések is megjelennek):

A konvenciók alternatívaként használhatók az egyes műveletek [ProducesResponseType]-nal történő explicit megjelölése helyett. További információ: Webes API-konvenciók használata.

Redoc

A Redoc a Swagger felhasználói felületének alternatívája. Ez hasonló, mert az OpenAPI-specifikációt használó webes API dokumentációs oldalát is tartalmazza. A különbség az, hogy a Redoc felhasználói felülete jobban összpontosít a dokumentációra, és nem biztosít interaktív felhasználói felületet az API teszteléséhez.

A Redoc engedélyezéséhez adja hozzá a middlewaret a Program.cs-hez.

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

Futtassa az alkalmazást, és navigáljon a(z) http://localhost:<port>/redoc-hez a Redoc felhasználói felületének megtekintéséhez.