Začínáme se službou NSwag a ASP.NET Core

Autor: Chris Nienaber, Rico Suter a Dave Brock

Zobrazení nebo stažení ukázkového kódu (postup stažení)

NSwag nabízí následující možnosti:

• Schopnost využívat generátor Swagger UI a Swagger.
• Flexibilní možnosti generování kódu

S NSwag nepotřebujete existující rozhraní API – můžete použít rozhraní API třetích stran, která zahrnují Swagger a generují implementaci klienta. NSwag umožňuje urychlit vývojový cyklus a snadno se přizpůsobit změnám rozhraní API.

Instalace balíčku

Nainstalujte NSwag do:

• Vygenerujte specifikaci Swaggeru pro implementované webové rozhraní API.
• Uživatelské rozhraní Swagger slouží k procházení a testování webového rozhraní API.
• Zadejte redoc a přidejte dokumentaci k rozhraní API pro webové rozhraní API.

Pokud chcete použít middleware NSwag ASP.NET Core, nainstalujte balíček NuGet NSwag.AspNetCore . Tento balíček obsahuje middleware pro generování a obsluhu specifikace Swagger, Swagger UI (v2 a v3) a reDoc UI. NSwag 14 podporuje pouze v3 specifikace Swagger UI.

K instalaci balíčku NSwag NuGet použijte jeden z následujících přístupů:

Visual Studio

• V okně konzoly Správce balíčků:

  • Přejděte do zobrazení>jiné konzoly windows Správce balíčků>

  • Přejděte do adresáře, ve kterém NSwagSample.csproj soubor existuje.

  • Spusťte následující příkaz:

    Install-Package NSwag.AspNetCore
    

• V dialogovém okně Spravovat balíčky NuGet:

  • Klikněte pravým tlačítkem na projekt v balíčku NuGet Průzkumník řešení> Manage
  • Nastavte zdroj balíčku na nuget.org.
  • Do vyhledávacího pole zadejte NSwag.AspNetCore.
  • Na kartě Procházet vyberte balíček NSwag.AspNetCore a klikněte na Nainstalovat.

Visual Studio pro Mac

• Klikněte pravým tlačítkem na složku Packages (Balíčky) v oblasti>řešení Přidat balíčky...
• V rozevíracím seznamu Zdroj v okně Přidat balíčky nastavte nuget.org.
• Do vyhledávacího pole zadejte NSwag.AspNetCore.
• V podokně výsledků vyberte balíček NSwag.AspNetCore a klikněte na Přidat balíček.

Visual Studio Code

Z integrovaného terminálu spusťte následující příkaz:

dotnet add NSwagSample.csproj package NSwag.AspNetCore

.NET CLI

Spusťte následující příkaz:

dotnet add NSwagSample.csproj package NSwag.AspNetCore

Přidání a konfigurace middlewaru Swaggeru

Přidejte a nakonfigurujte Swagger v aplikaci ASP.NET Core provedením následujících kroků:

• Přidejte generátor OpenApi do kolekce služeb v Program.cs:

var builder = WebApplication.CreateBuilder(args);

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

• Povolte middleware pro obsluhu vygenerované specifikace OpenApi, uživatelského rozhraní Swaggeru a uživatelského rozhraní Redoc také v 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())
}

• Spustit aplikaci Přejděte na:
  • http://localhost:<port>/swagger pro zobrazení uživatelského rozhraní Swaggeru.
  • http://localhost:<port>/swagger/v1/swagger.json pro zobrazení specifikace Swaggeru.

Generování kódu

Možnosti generování kódu NSwag můžete využít tak, že zvolíte jednu z následujících možností:

• NSwagStudio: Desktopová aplikace pro Windows pro generování kódu klienta rozhraní API v jazyce C# nebo TypeScript.
• Balíčky NuGet NSwag.CodeGeneration.CSharp nebo NSwag.CodeGeneration.TypeScript pro generování kódu uvnitř projektu.
• NSwag z příkazového řádku.
• Balíček NuGet NSwag.MSBuild .
• Připojená služba OpenAPI (Swagger): Připojená služba sady Visual Studio pro generování kódu klienta rozhraní API v jazyce C# nebo TypeScript. Generuje také kontrolery C# pro služby OpenAPI pomocí NSwag.

Generování kódu pomocí NSwagStudio

• Nainstalujte NSwagStudio podle pokynů v úložišti NSwagStudio GitHub. Na stránce verze NSwag si můžete stáhnout verzi xcopy, která se dá spustit bez oprávnění instalace a správce.
• Spusťte NSwagStudio a zadejte swagger.json adresu URL souboru do textového pole Swagger Specification URL . Například http://localhost:5232/swagger/v1/swagger.json.
• Kliknutím na tlačítko Vytvořit místní kopii vygenerujete reprezentaci JSON specifikace Swaggeru.

• V oblasti Výstupy klikněte na zaškrtávací políčko Klienta CSharp. V závislosti na projektu můžete také zvolit klient TypeScriptu nebo řadič webového rozhraní API CSharp. Pokud vyberete CSharp Web API Controller, specifikace služby znovu sestaví službu, která slouží jako zpětné generování.
• Kliknutím na Generovat výstupy vytvoříte úplnou implementaci klienta C# projektu TodoApi.NSwag . Pokud chcete zobrazit vygenerovaný kód klienta, klikněte na kartu Klient 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;
        }

        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

Tip

Kód klienta jazyka C# se generuje na základě výběru na kartě Nastavení . Upravte nastavení tak, aby prováděla úlohy, jako je výchozí přejmenování oboru názvů a generování synchronních metod.

• Zkopírujte vygenerovaný kód C# do souboru v klientském projektu, který bude rozhraní API využívat.
• Začněte využívat webové rozhraní API:

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

Přizpůsobení dokumentace k rozhraní API

OpenApi poskytuje možnosti pro dokumentaci objektového modelu, aby se usnadnila spotřeba webového rozhraní API.

Informace a popis rozhraní API

Aktualizujte Program.csAddOpenApiDocument informace o dokumentu webového rozhraní API a uveďte další informace, jako je autor, licence a popis. Nejprve naimportujte NSwag obor názvů pro použití OpenApi tříd.

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

Uživatelské rozhraní Swagger zobrazí informace o verzi:

Komentáře XML

Pokud chcete povolit komentáře XML, proveďte následující kroky:

Visual Studio

• Klikněte pravým tlačítkem myši na projekt v Průzkumník řešení a vyberte Edit <project_name>.csproj.
• Do souboru přidejte ručně zvýrazněné řádky .csproj :

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

Visual Studio pro Mac

• Na panelu řešení stiskněte ovládací prvek a klikněte na název projektu. Přejděte do části Nástroje>upravit soubor.
• Do souboru přidejte ručně zvýrazněné řádky .csproj :

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

Visual Studio Code

Do souboru přidejte ručně zvýrazněné řádky .csproj :

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

.NET CLI

Do souboru přidejte ručně zvýrazněné řádky .csproj :

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

Povolení komentářů XML poskytuje informace o ladění pro nezdokumentované veřejné typy a členy. Nezdokumentované typy a členy jsou označeny upozorněním. Například následující zpráva indikuje porušení kódu upozornění 1591:

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

Chcete-li potlačit upozornění na úrovni projektu, definujte seznam kódů upozornění oddělených středníkem, které se mají v souboru projektu ignorovat. Připojte kódy upozornění, aby $(NoWarn); se použily i výchozí hodnoty jazyka C#.

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

Chcete-li potlačit upozornění pouze pro konkrétní členy, uzavřete kód do #pragma direktivy preprocesoru upozornění . Tento přístup je užitečný pro kód, který by neměl být zpřístupněn prostřednictvím dokumentace k rozhraní API. V následujícím příkladu je kód upozornění CS1591 ignorován pro celou TodoContext třídu. Vynucení kódu upozornění se obnoví na konci definice třídy. Zadejte více kódů upozornění se seznamem odděleným čárkami.

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

Datové poznámky

Označte model pomocí atributů nalezených v System.ComponentModel.DataAnnotations oboru názvů, který pomáhá řídit komponenty uživatelského rozhraní Swagger.

[Required] Přidejte atribut do Name vlastnosti TodoItem třídy:

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

Přítomnost tohoto atributu změní chování uživatelského rozhraní a změní základní schéma JSON:

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

S rostoucím využitím datových poznámek ve webovém rozhraní API se stránky nápovědy k uživatelskému rozhraní a rozhraní API stanou popisnější a užitečnější.

Popis typů odpovědí

Vývojáři, kteří využívají webové rozhraní API, se nejvíce zajímají o to, co se vrátí – konkrétně typy odpovědí a kódy chyb (pokud nejsou standardní). Typy odpovědí a kódy chyb jsou označené v komentářích XML a datových poznámkách.

Akce Create vrátí stavový kód HTTP 201 při úspěchu. Stavový kód HTTP 400 se vrátí při odeslání textu nullpožadavku . Bez správné dokumentace v uživatelském rozhraní Swaggeru spotřebitel nemá znalosti o těchto očekávaných výsledcích. Tento problém opravte přidáním zvýrazněných řádků v následujícím příkladu:

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

Uživatelské rozhraní Swagger teď jasně dokumentuje očekávané kódy odpovědí HTTP (a zobrazují se také komentáře XML):

Konvence lze použít jako alternativu k explicitní dekódování jednotlivých akcí pomocí [ProducesResponseType]. Další informace najdete v tématu Použití konvencí webového rozhraní API.

Redoc

Redoc je alternativou k uživatelskému rozhraní Swagger. Je to podobné, protože poskytuje také stránku dokumentace pro webové rozhraní API pomocí specifikace OpenAPI. Rozdíl je v tom, že uživatelské rozhraní Redoc se zaměřuje na dokumentaci a neposkytuje interaktivní uživatelské rozhraní pro testování rozhraní API.

Pokud chcete povolit Redoc, přidejte jeho middleware do 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 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";
    });
}

Spusťte aplikaci a přejděte k http://localhost:<port>/redoc zobrazení uživatelského rozhraní Redoc: