Kom igång med NSwag och ASP.NET Core

Av Rico Suter och Dave Brock

Visa eller ladda ned exempelkod (hur du laddar ned)

NSwag erbjuder följande funktioner:

• Möjligheten att använda Swagger-användargränssnittet och Swagger-generatorn.
• Flexibla funktioner för kodgenerering.

Med NSwag behöver du inget befintligt API– du kan använda API:er från tredje part som införlivar Swagger och genererar en klientimplementering. Med NSwag kan du påskynda utvecklingscykeln och enkelt anpassa dig till API-ändringar.

Paketinstallation

Installera NSwag för att:

• Generera Swagger-specifikationen för det implementerade webb-API:et.
• Använd Swagger-användargränssnittet för att bläddra och testa webb-API:et.
• Hantera Redoc för att lägga till API-dokumentation för webb-API:et.

Om du vill använda NSwag ASP.NET Core-mellanprogrammet installerar du NuGet-paketet NSwag.AspNetCore . Det här paketet innehåller mellanprogrammet för att generera och hantera Swagger-specifikationen, Swagger UI (v2 och v3) och ReDoc-användargränssnittet. NSwag 14 stöder endast v3 av Swagger UI-specifikationen.

Använd någon av följande metoder för att installera NSwag NuGet-paketet:

dotnet add NSwagSample.csproj package NSwag.AspNetCore

dotnet add NSwagSample.csproj package NSwag.AspNetCore

Lägga till och konfigurera Swagger-mellanprogram

Lägg till och konfigurera Swagger i din ASP.NET Core-app genom att utföra följande steg:

• Lägg till OpenApi-generatorn i tjänstesamlingen i Program.cs:

var builder = WebApplication.CreateBuilder(args);

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

• Aktivera mellanprogrammet för att hantera den genererade OpenApi-specifikationen, Swagger-användargränssnittet och Redoc-användargränssnittet, även i 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())
}

• Starta appen. Gå till:
  • http://localhost:<port>/swagger för att visa Swagger-användargränssnittet.
  • http://localhost:<port>/swagger/v1/swagger.json för att visa Swagger-specifikationen.

Kodgenerering

Du kan dra nytta av NSwags funktioner för kodgenerering genom att välja något av följande alternativ:

• NSwagStudio: En Windows-skrivbordsapp för att generera API-klientkod i C# eller TypeScript.
• NSwag.CodeGeneration.CSharp eller NSwag.CodeGeneration.TypeScript NuGet-paket för kodgenerering i projektet.
• NSwag från kommandoraden.
• NSwag.MSBuild NuGet-paketet.
• Den anslutna tjänsten Unchase OpenAPI (Swagger): En Visual Studio Connected Service för att generera API-klientkod i C# eller TypeScript. Genererar även C#-styrenheter för OpenAPI-tjänster med NSwag.

Generera kod med NSwagStudio

• Installera NSwagStudio genom att följa anvisningarna på NSwagStudio GitHub-lagringsplatsen. På sidan för NSwag-versionen kan du ladda ned en xcopy-version som kan startas utan installations- och administratörsbehörighet.
• Starta NSwagStudio och ange swagger.json fil-URL:en i textrutan Swagger Specification URL . Till exempel http://localhost:5232/swagger/v1/swagger.json.
• Klicka på knappen Skapa lokal kopia för att generera en JSON-representation av din Swagger-specifikation.

• I området Utdata klickar du på kryssrutan CSharp-klient . Beroende på ditt projekt kan du också välja TypeScript-klient eller CSharp Web API Controller. Om du väljer CSharp Web API Controller återskapar en tjänstspecifikation tjänsten och fungerar som en omvänd generering.
• Klicka på Generera utdata för att skapa en fullständig C#-klientimplementering av Projektet TodoApi.NSwag . Om du vill se den genererade klientkoden klickar du på fliken CSharp-klient :

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

• Kopiera den genererade C#-koden till en fil i klientprojektet som ska använda API:et.
• Börja använda webb-API:et:

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

Anpassa API-dokumentation

OpenApi innehåller alternativ för att dokumentera objektmodellen för att underlätta förbrukningen av webb-API:et.

API-information och beskrivning

Uppdatera Program.cs i AddOpenApiDocument för att konfigurera dokumentinformationen för webb-API:et och inkludera mer information, såsom författare, licens och beskrivning. NSwag Importera namnområdet först för att använda klassernaOpenApi.

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-användargränssnittet visar versionens information:

XML-kommentarer

Utför följande steg för att aktivera XML-kommentarer:

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

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

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

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

Aktivering av XML-kommentarer ger felsökningsinformation för odokumenterade offentliga typer och medlemmar. Odokumenterade typer och medlemmar indikeras av varningsmeddelandet. Följande meddelande anger till exempel ett brott mot varningskoden 1591:

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

Om du vill förhindra varningar i hela projektet definierar du en semikolonavgränsad lista med varningskoder som ska ignoreras i projektfilen. Om du lägger till varningskoderna på $(NoWarn); tillämpas även C#-standardvärdena.

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

Om du bara vill förhindra varningar för specifika medlemmar omsluter du koden i #pragma warning preprocessor-direktiv. Den här metoden är användbar för kod som inte ska exponeras via API-dokumenten. I följande exempel ignoreras varningskoden CS1591 för hela klassen TodoContext. Tillämpning av varningskoden återställs i slutet av klassdefinitionen. Ange flera varningskoder med en kommaavgränsad lista.

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

Dataanteckningar

Markera modellen med attribut, som finns i System.ComponentModel.DataAnnotations namnrymd, för att hjälpa till att driva Swagger UI-komponenterna.

Lägg till attributet [Required] i egenskapen Name för klassen TodoItem:

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

Förekomsten av det här attributet ändrar användargränssnittets beteende och ändrar det underliggande JSON-schemat:

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

När användningen av dataanteckningar i webb-API:et ökar blir hjälpsidorna för användargränssnittet och API:et mer beskrivande och användbara.

Beskriva svarstyper

Utvecklare som använder ett webb-API bryr sig mest om vad som returneras – särskilt svarstyper och felkoder (om inte standard). Svarstyperna och felkoderna anges i XML-kommentarer och dataanteckningar.

Åtgärden Create returnerar en HTTP 201-statuskod när den lyckas. En HTTP 400-statuskod returneras när den publicerade begärandetexten är null. Utan korrekt dokumentation i Swagger-användargränssnittet saknar konsumenten kunskap om dessa förväntade resultat. Åtgärda problemet genom att lägga till de markerade raderna i följande exempel:

/// <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-användargränssnittet dokumenterar nu tydligt de förväntade HTTP-svarskoderna (och XML-kommentarerna visas också):

Konventioner kan användas som ett alternativ till att uttryckligen dekorera enskilda åtgärder med [ProducesResponseType]. Mer information finns i Använda webb-API-konventioner.

Redoc

Redoc är ett alternativ till Swagger-användargränssnittet. Det liknar det eftersom det även innehåller en dokumentationssida för webb-API:et med hjälp av OpenAPI-specifikationen. Skillnaden är att Redoc-användargränssnittet är mer fokuserat på dokumentationen och inte tillhandahåller något interaktivt användargränssnitt för att testa API:et.

Om du vill aktivera Redoc lägger du till mellanprogrammet i 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";
    });
}

Kör programmet och navigera till http://localhost:<port>/redoc för att visa Redoc-användargränssnittet:

Av Rico Suter och Dave Brock

Visa eller ladda ned exempelkod (hur du laddar ned)

NSwag erbjuder följande funktioner:

• Möjligheten att använda Swagger-användargränssnittet och Swagger-generatorn.
• Flexibla funktioner för kodgenerering.

Med NSwag behöver du inget befintligt API– du kan använda API:er från tredje part som införlivar Swagger och genererar en klientimplementering. Med NSwag kan du påskynda utvecklingscykeln och enkelt anpassa dig till API-ändringar.

Registrera NSwag-mellanprogrammet

Registrera NSwag-mellanprogrammet för att:

• Generera Swagger-specifikationen för det implementerade webb-API:et.
• Använd Swagger-användargränssnittet för att bläddra och testa webb-API:et.

Om du vill använda NSwag ASP.NET Core-mellanprogrammet installerar du NuGet-paketet NSwag.AspNetCore . Det här paketet innehåller mellanprogrammet för att generera och hantera Swagger-specifikationen, Swagger UI (v2 och v3) och ReDoc-användargränssnittet.

Använd någon av följande metoder för att installera NSwag NuGet-paketet:

dotnet add TodoApi.csproj package NSwag.AspNetCore

dotnet add TodoApi.csproj package NSwag.AspNetCore

Lägga till och konfigurera Swagger-mellanprogram

Lägg till och konfigurera Swagger i din ASP.NET Core-app genom att utföra följande steg:

• Startup.ConfigureServices I metoden registrerar du nödvändiga Swagger-tjänster:

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

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

• Startup.Configure I metoden aktiverar du mellanprogrammet för att hantera den genererade Swagger-specifikationen och Swagger-användargränssnittet:

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

• Starta appen. Gå till:
  • http://localhost:<port>/swagger för att visa Swagger-användargränssnittet.
  • http://localhost:<port>/swagger/v1/swagger.json för att visa Swagger-specifikationen.

Kodgenerering

Du kan dra nytta av NSwags funktioner för kodgenerering genom att välja något av följande alternativ:

• NSwagStudio: En Windows-skrivbordsapp för att generera API-klientkod i C# eller TypeScript.
• NSwag.CodeGeneration.CSharp eller NSwag.CodeGeneration.TypeScript NuGet-paket för kodgenerering i projektet.
• NSwag från kommandoraden.
• NSwag.MSBuild NuGet-paketet.
• Den anslutna tjänsten Unchase OpenAPI (Swagger): En Visual Studio Connected Service för att generera API-klientkod i C# eller TypeScript. Genererar även C#-styrenheter för OpenAPI-tjänster med NSwag.

Generera kod med NSwagStudio

• Installera NSwagStudio genom att följa anvisningarna på NSwagStudio GitHub-lagringsplatsen. På NSwag-versionssidan kan du ladda ned en xcopy-version som kan startas utan installations- och administratörsbehörighet.

• Starta NSwagStudio och ange swagger.json fil-URL:en i textrutan Swagger Specification URL . Till exempel http://localhost:44354/swagger/v1/swagger.json.

• Klicka på knappen Skapa lokal kopia för att generera en JSON-representation av din Swagger-specifikation.

  

• I området Utdata klickar du på kryssrutan CSharp-klient . Beroende på ditt projekt kan du också välja TypeScript-klient eller CSharp Web API Controller. Om du väljer CSharp Web API Controller återskapar en tjänstspecifikation tjänsten och fungerar som en omvänd generering.

• Klicka på Generera utdata för att skapa en fullständig C#-klientimplementering av Projektet TodoApi.NSwag . Om du vill se den genererade klientkoden klickar du på fliken CSharp-klient :

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

• Kopiera den genererade C#-koden till en fil i klientprojektet som ska använda API:et.
• Börja använda webb-API:et:

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

Anpassa API-dokumentation

Swagger innehåller alternativ för att dokumentera objektmodellen för att underlätta förbrukningen av webb-API:et.

API-information och beskrivning

I metoden Startup.ConfigureServices lägger en konfigurationsfunktion som skickas till metoden AddSwaggerDocument till information som författare, licens och beskrivning.

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-användargränssnittet visar versionens information:

XML-kommentarer

Utför följande steg för att aktivera XML-kommentarer:

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

Dataanteckningar

Eftersom NSwag använder Reflektion och den rekommenderade returtypen för webb-API-åtgärder är ActionResult<T>, kan den bara härleda returtypen som definieras av T. Du kan inte automatiskt härleda andra möjliga returtyper.

Tänk på följande exempel:

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

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

Föregående åtgärd returnerar ActionResult<T>. Inuti åtgärden returnerar CreatedAtRoute. Eftersom kontrollanten [ApiController] har attributet är ett BadRequest svar också möjligt. Mer information finns i automatiska HTTP 400-svar. Använd dataanteckningar för att tala om för klienter vilka HTTP-statuskoder den här åtgärden är känd för att returnera. Markera åtgärden med följande attribut:

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

I ASP.NET Core 2.2 eller senare kan du använda konventioner i stället för att uttryckligen dekorera enskilda åtgärder med [ProducesResponseType]. Mer information finns i Använda webb-API-konventioner.

Swagger-generatorn kan nu beskriva den här åtgärden korrekt och genererade klienter vet vad de får när de anropar slutpunkten. Som en rekommendation markerar du alla åtgärder med dessa attribut.

Riktlinjer för vilka HTTP-svar dina API-åtgärder ska returnera finns i RFC 9110: HTTP-semantik (avsnitt 9.3. Metoddefinitioner).