Aan de slag met NSwag en ASP.NET Core

Door Rico Suter en Dave Brock

Voorbeeldcode bekijken of downloaden (hoe download je)

NSwag biedt de volgende mogelijkheden:

• De mogelijkheid om de Swagger UI en Swagger generator te gebruiken.
• Flexibele mogelijkheden voor het genereren van code.

Met NSwag hebt u geen bestaande API nodig. U kunt API's van derden gebruiken die Swagger bevatten en een clientimplementatie genereren. Met NSwag kunt u de ontwikkelingscyclus versnellen en eenvoudig aanpassen aan API-wijzigingen.

Installatie van pakketten

Installeer NSwag om:

• Genereer de Swagger-specificatie voor de geïmplementeerde web-API.
• Serveer de Swagger-gebruikersinterface om door de web-API te bladeren en te testen.
• Serveer de Redoc om API-documentatie toe te voegen voor de web-API.

Als u de NSwag ASP.NET Core middleware wilt gebruiken, installeert u het NSwag.AspNetCore NuGet-pakket. Dit pakket bevat de middleware voor het genereren en leveren van de Swagger-specificatie, Swagger UI (v2 en v3) en ReDoc UI. NSwag 14 ondersteunt alleen v3 van de Swagger UI-specificatie.

Gebruik een van de volgende methoden om het NSwag NuGet-pakket te installeren:

Visual Studio

• Vanuit het venster Package Manager Console:

  • Ga naar View>Andere Vensters>Package Manager Console

  • Navigeer naar de map waarin het NSwagSample.csproj bestand bestaat

  • Voer de volgende opdracht uit:

    Install-Package NSwag.AspNetCore
    

• In het dialoogvenster NuGet-pakketten beheren:

  • Klik met de rechtermuisknop op het project in Solution Explorer>NuGet-pakketten beheren
  • Stel de pakketbron in op 'nuget.org'
  • Voer NSwag.AspNetCore in het zoekvak in
  • Selecteer het pakket 'NSwag.AspNetCore' op het tabblad Bladeren en klik op Installeren

Visual Studio voor Mac

• Klik met de rechtermuisknop op de map Packages in Solution Pad>Add Packages...
• Stel het venster Pakket Toevoegen de vervolgkeuzelijst Bron in op "nuget.org"
• Voer NSwag.AspNetCore in het zoekvak in
• Selecteer het pakket NSwag.AspNetCore in het resultatenvenster en klik op Pakket toevoegen

Visual Studio Code

Voer de volgende opdracht uit vanuit de Integrated Terminal:

dotnet add NSwagSample.csproj package NSwag.AspNetCore

.NET CLI

Voer de volgende opdracht uit:

dotnet add NSwagSample.csproj package NSwag.AspNetCore

Swagger middleware toevoegen en configureren

Voeg Swagger toe en configureer deze in uw ASP.NET Core-app door de volgende stappen uit te voeren:

• Voeg de OpenApi-generator toe aan de servicesverzameling in Program.cs:

var builder = WebApplication.CreateBuilder(args);

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

• Schakel de middleware in voor het leveren van de gegenereerde OpenApi-specificatie, de Swagger UI en de Redoc UI, ook in 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())
}

• Start de app. Navigeer naar:
  • http://localhost:<port>/swagger om de Swagger-gebruikersinterface weer te geven.
  • http://localhost:<port>/swagger/v1/swagger.json om de Swagger-specificatie weer te geven.

Code genereren

U kunt profiteren van de mogelijkheden voor het genereren van code van NSwag door een van de volgende opties te kiezen:

• NSwagStudio: een Windows-bureaublad-app voor het genereren van API-clientcode in C# of TypeScript.
• De NSwag.CodeGeneration.CSharp - of NSwag.CodeGeneration.TypeScript NuGet-pakketten voor het genereren van code in uw project.
• NSwag vanaf de opdrachtregel.
• Het NSwag.MSBuild NuGet-pakket.
• De Unchase OpenAPI (Swagger) Connected Service: een Visual Studio Connected Service voor het genereren van API-clientcode in C# of TypeScript. Genereert ook C#-controllers voor OpenAPI-services met NSwag.

Code genereren met NSwagStudio

• Installeer NSwagStudio door de instructies te volgen in de GitHub-opslagplaats van NSwagStudio. Op de releasepagina van NSwag kunt u een xcopy-versie downloaden die kan worden gestart zonder installatie- en beheerdersbevoegdheden.
• Start NSwagStudio en voer de swagger.json bestands-URL in het tekstvak Swagger Specification URL in. Bijvoorbeeld: http://localhost:5232/swagger/v1/swagger.json.
• Klik op de knop Lokaal kopiëren maken om een JSON-weergave van uw Swagger-specificatie te genereren.

• Klik in het gebied Uitvoer op het selectievakje CSharp Client . Afhankelijk van uw project kunt u ook TypeScript-client of CSharp-web-API-controller kiezen. Als u CSharp Web API Controller selecteert, wordt de service opnieuw opgebouwd met een servicespecificatie, die fungeert als omgekeerde generatie.
• Klik op Uitvoer genereren om een volledige C#-client te produceren van het TodoApi.NSwag-project . Als u de gegenereerde clientcode wilt zien, klikt u op het tabblad CSharp Client :

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

Aanbeveling

De C#-clientcode wordt gegenereerd op basis van selecties op het tabblad Instellingen . Wijzig de instellingen om taken uit te voeren, zoals het wijzigen van de naam van de standaardnaamruimte en het genereren van synchrone methoden.

• Kopieer de gegenereerde C#-code naar een bestand in het clientproject dat de API verbruikt.
• Begin met het gebruik van de web-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);

API-documentatie aanpassen

OpenApi biedt opties voor het documenteren van het objectmodel om het verbruik van de web-API te vereenvoudigen.

API-informatie en -beschrijving

Werk Program.cs bij in AddOpenApiDocument om de documentgegevens van de Web API te configureren en meer informatie toe te voegen, zoals de auteur, licentie en beschrijving. Importeer eerst de NSwag naamruimte om de OpenApi klassen te gebruiken.

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

De Swagger-gebruikersinterface geeft de versiegegevens weer:

XML-opmerkingen

Voer de volgende stappen uit om XML-opmerkingen in te schakelen:

Visual Studio

• Klik met de rechtermuisknop op het project in Solution Explorer en selecteer Edit <project_name>.csproj.
• Voeg handmatig de gemarkeerde regels toe aan het .csproj-bestand:

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

Visual Studio voor Mac

• Druk in het Solution Padop control en klik op de projectnaam. Ga naar Extra>Bewerk bestand.
• Voeg handmatig de gemarkeerde regels toe aan het .csproj-bestand:

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

Visual Studio Code

Voeg handmatig de gemarkeerde regels toe aan het .csproj-bestand:

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

.NET CLI

Voeg handmatig de gemarkeerde regels toe aan het .csproj-bestand:

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

Het inschakelen van XML-opmerkingen biedt foutopsporingsinformatie voor niet-gedocumenteerde openbare typen en leden. Ongedocumenteerde typen en leden worden aangeduid door het waarschuwingsbericht. Het volgende bericht geeft bijvoorbeeld een schending van waarschuwingscode 1591 aan:

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

Als u waarschuwingen voor het hele project wilt onderdrukken, definieert u een door puntkomma's gescheiden lijst met waarschuwingscodes die in het projectbestand moeten worden genegeerd. Als u de waarschuwingscodes toevoegt aan $(NoWarn); worden de standaardwaarden van C# ook toegepast.

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

Als u alleen waarschuwingen voor specifieke leden wilt onderdrukken, plaatst u de code in #pragma waarschuwing preprocessorrichtlijnen. Deze methode is handig voor code die niet beschikbaar moet worden gesteld via de API-documenten. In het volgende voorbeeld wordt waarschuwingscode CS1591 genegeerd voor de hele TodoContext klasse. Het handhaven van de waarschuwingscode wordt hersteld aan het einde van de class-definitie. Geef meerdere waarschuwingscodes op met een door komma's gescheiden lijst.

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

Gegevensaantekeningen

Markeer het model met kenmerken, gevonden in de System.ComponentModel.DataAnnotations naamruimte, om de Swagger UI-onderdelen te helpen aan te sturen.

Voeg het kenmerk [Required] toe aan de eigenschap Name van de klasse 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; }
}

De aanwezigheid van dit kenmerk wijzigt het gedrag van de gebruikersinterface en wijzigt het onderliggende JSON-schema:

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

Naarmate het gebruik van gegevensaantekeningen in de web-API toeneemt, worden de helppagina's voor de gebruikersinterface en API meer beschrijvend en nuttiger.

Antwoordtypen beschrijven

Ontwikkelaars die een web-API gebruiken, houden zich het meest bezig met wat er wordt geretourneerd, met name antwoordtypen en foutcodes (indien niet standaard). De antwoordtypen en foutcodes worden aangeduid in de XML-opmerkingen en gegevensaantekeningen.

De Create-actie retourneert een HTTP 201-statuscode bij succes. Er wordt een HTTP 400-statuscode geretourneerd wanneer de geplaatste aanvraagbody is null. Zonder de juiste documentatie in de Swagger-gebruikersinterface mist de consument kennis van deze verwachte resultaten. Los dit probleem op door de gemarkeerde regels toe te voegen in het volgende voorbeeld:

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

De Swagger-gebruikersinterface documentert nu duidelijk de verwachte HTTP-antwoordcodes (en de XML-opmerkingen worden ook weergegeven):

Conventies kunnen worden gebruikt als alternatief voor het expliciet decoreren van afzonderlijke acties met [ProducesResponseType]. Zie Web-API-conventies gebruikenvoor meer informatie.

Redoc

Redoc is een alternatief voor de Swagger-gebruikersinterface. Het is vergelijkbaar omdat het ook een documentatiepagina voor de web-API biedt met behulp van de OpenAPI-specificatie. Het verschil is dat de Redoc-gebruikersinterface meer gericht is op de documentatie en geen interactieve gebruikersinterface biedt om de API te testen.

Als u Redoc wilt inschakelen, voegt u de middleware toe aan 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";
    });
}

Voer de toepassing uit en navigeer naar http://localhost:<port>/redoc om de Redoc-gebruikersinterface te bekijken.