Erste Schritte mit NSwag und ASP.NET Core

Von Christoph Nienaber, Rico Suter und Dave Brock

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)

NSwag bietet die folgenden Funktionen:

• Die Möglichkeit, die Swagger-Benutzeroberfläche und den Swagger-Generator zu verwenden.
• Flexible Codegenerierung.

Mit NSwag brauchen Sie keine vorhandene API. Sie können APIs von Drittanbietern verwenden, die Swagger einbinden und eine Client Implementierung generieren. Mit NSwag können Sie den Entwicklungszyklus beschleunigen und sich problemlos an API-Änderungen anpassen.

Paketinstallation

Installieren Sie NSwag für Folgendes:

• Generieren Sie die Swagger-Spezifikation für die implementierte Web-API.
• Stellen Sie die Swagger-Benutzeroberfläche zum Durchsuchen und Testen die Web-API bereit.
• Stellen Sie ReDoc bereit, um die API-Dokumentation für die Web-API hinzuzufügen.

Um NSwag mit ASP.NET Core-Middleware zu verwenden, installieren Sie das NuGet-Paket NSwag.AspNetCore. Dieses Paket enthält die Middleware zum Generieren und Bereitstellen der Swagger-Spezifikation, der Swagger-Benutzeroberfläche (v2 und v3) und der ReDoc-Benutzeroberfläche. NSwag 14 unterstützt nur v3 der Swagger UI-Spezifikation.

Verwenden Sie einen der folgenden Ansätze, um das NuGet-Paket „NSwag“ zu installieren:

dotnet add NSwagSample.csproj package NSwag.AspNetCore

dotnet add NSwagSample.csproj package NSwag.AspNetCore

Hinzufügen und Konfigurieren von Swagger-Middleware

Sie können Swagger in Ihrer ASP.NET Core-App hinzufügen und konfigurieren, indem Sie die folgenden Schritte ausführen:

• Fügen Sie den OpenApi-Generator zur Sammlung „services“ in Program.cs hinzu:

var builder = WebApplication.CreateBuilder(args);

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

• Aktivieren Sie die Middleware für die Bereitstellung der generierten OpenApi-Spezifikation, der Swagger-Benutzeroberfläche und der ReDoc-Benutzeroberfläche, auch 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())
}

• Starten Sie die App. Navigieren Sie zu:
  • http://localhost:<port>/swagger, um die Swagger-Benutzeroberfläche anzuzeigen.
  • http://localhost:<port>/swagger/v1/swagger.json, um die Swagger-Spezifikation anzuzeigen.

Codeerzeugung

Durch die Auswahl einer der folgenden Optionen können Sie die Funktion zur Codegenerierung von NSwag nutzen:

• NSwagStudio: Dies ist eine Windows-Desktop-App zum Generieren von API-Clientcode in C# und TypeScript.
• Die NuGet-Pakete NSwag.CodeGeneration.CSharp oder NSwag.CodeGeneration.TypeScript, um Code innerhalb des Projekts zu generieren.
• NSwag über die Befehlszeile.
• Das NuGet-Paket NSwag.MSBuild.
• Unchase OpenAPI (Swagger) Connected Service: Dies ist ein mit Visual Studio verbundener Dienst zum Generieren von API-Clientcode in C# oder TypeScript. Es werden auch C#-Controller für OpenAPI-Dienste mit NSwag generiert.

Generieren von Code mit NSwagStudio

• Installieren Sie NSwagStudio anhand der Anweisungen im NSwagStudio-GitHub-Repository. Auf der Releaseseite von NSwag können Sie eine XCOPY-Version herunterladen, die ohne Installation und Administratorrechte gestartet werden kann.
• Starten Sie NSwagStudio, und geben Sie die Datei-URL swagger.json in das Textfeld URL zur Spezifizierung des Swaggers ein. Beispiel: http://localhost:5232/swagger/v1/swagger.json.
• Klicken Sie auf die Schaltfläche Lokale Kopie erstellen, um eine JSON-Darstellung Ihrer Swagger-Spezifikation zu generieren.

• Aktivieren Sie im Bereich Ausgaben das Kontrollkästchen CSharp-Client. Je nach Ihrem Projekt können Sie auch den TypeScript Client oder CSharp-Web-API-Controller auswählen. Bei der Auswahl des CSharp-Web-API-Controllers erstellt eine Dienstspezifikation den Dienst neu, und dient als eine umgekehrte Generierung.
• Klicken Sie auf Ausgaben generieren, um eine vollständige C#-Clientimplementierung des TodoApi.NSwag-Projekts durchzuführen. Klicken Sie auf die Registerkarte CSharp-Client, damit der generierte Clientcode angezeigt wird:

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

• Kopieren Sie den generierten C#-Code in eine Datei in das Clientprojekt, das die API verwendet.
• Verwendung der 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);

Anpassen der API-Dokumentation

OpenApi umfasst Optionen zum Dokumentieren des Objektmodells, um die Verwendung der Web-API zu vereinfachen.

API-Informationen und -Beschreibung

Aktualisieren Sie AddOpenApiDocument in Program.cs, um die Dokumentinformationen der Web-API zu konfigurieren, und fügen Sie weitere Informationen wie Autor, Lizenz und Beschreibung hinzu. Importieren Sie zuerst den Namespace NSwag, um die OpenApi-Klassen zu verwenden.

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

Auf der Swagger-Benutzeroberfläche werden die Versionsinformationen angezeigt:

XML-Kommentare

Um XML-Kommentaren zu aktivieren, führen Sie die folgenden Schritte aus:

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

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

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

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

Das Aktivieren von XML-Kommentaren stellt Debuginformationen zu nicht-dokumentierten öffentlichen Typen und Members bereit. Auf nicht dokumentierte Typen und Member wird durch die Warnmeldung verwiesen. Die folgende Meldung macht z.B. durch den Warnungscode 1591 auf einen Verstoß aufmerksam:

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

Um Warnungen projektübergreifend zu unterdrücken, definieren Sie eine Liste der zu ignorierenden Warnungscodes (mit Semikolon als Trennzeichen). Das Anfügen von Warnungscodes an $(NoWarn); gilt auch für die C#-Standardwerte.

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

Um Warnungen nur für bestimmte Member zu unterdrücken, schließen Sie den Code in #pragma warning-Präprozessordirektiven ein. Dieser Ansatz eignet sich für Code, der nicht über die API-Dokumentation verfügbar gemacht werden soll. Im folgenden Beispiel wird der Warnungscode CS1591 für die gesamte Klasse TodoContext ignoriert. Das Erzwingen des Warnungscodes wird am Ende der Klassendefinition wiederhergestellt. Geben Sie mehrere Warnungscodes in einer kommagetrennten Liste an.

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

Datenanmerkungen

Markieren Sie das Modell mit Attributen, die sich im Namespace System.ComponentModel.DataAnnotations befinden, um die Swagger-UI-Komponenten zu steuern.

Fügen Sie das [Required]-Attribut der Name-Eigenschaft der TodoItem-Klasse hinzu:

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

Das Vorhandensein dieses Attributs ändert das Verhalten der Benutzeroberfläche und des zugrunde liegenden JSON-Schemas:

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

Mit zunehmender Verwendung von Datenanmerkungen in der Web-API werden die UI- und API-Hilfeseiten beschreibender und nützlicher.

Beschreiben von Antworttypen

Entwickler, die eine Web-API nutzen, interessieren sich vor allem dafür, welche Antworttypen und Fehlercodes zurückgegeben werden (wenn diese nicht dem Standard entsprechen). Die Antworttypen und Fehlercodes sind in den XML-Kommentaren und Datenanmerkungen gekennzeichnet.

Die Aktion Create gibt bei einer erfolgreichen Anforderung den Statuscode „HTTP 201“ zurück. Der Statuscode „HTTP 400“ wird zurückgegeben, wenn der gesendete Anforderungstext null ist. Ohne richtige Dokumentation in der Swagger-Benutzeroberfläche fehlt dem Consumer das Wissen über diese erwarteten Ergebnisse. Sie können dieses Problem beheben, indem Sie die hervorgehobenen Zeilen im folgenden Beispiel hinzufügen:

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

Die Swagger-Benutzeroberfläche dokumentiert nun deutlich die erwarteten HTTP-Antwortcodes (und die XML-Kommentare werden ebenfalls angezeigt):

Alternativ können Konventionen verwendet werden, um einzelne Aktionen explizit mit [ProducesResponseType] zu ergänzen. Weitere Informationen finden Sie unter Verwenden von Web-API-Konventionen.

ReDoc

ReDoc ist eine Alternative zur Swagger-Benutzeroberfläche. Sie ist ähnlich, da sie mit der OpenAPI-Spezifikation auch eine Dokumentationsseite für die Web-API bereitstellt. Der Unterschied besteht darin, dass sich die ReDoc-Benutzeroberfläche stärker auf die Dokumentation konzentriert. Sie stellt keine interaktive Benutzeroberfläche zum Testen der API bereit.

Um ReDoc zu aktivieren, fügen Sie die Middleware zu Program.cs hinzu:

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

Führen Sie die Anwendung aus, und navigieren Sie zu http://localhost:<port>/redoc, um die ReDoc-Benutzeroberfläche anzuzeigen:

Von Christoph Nienaber, Rico Suter und Dave Brock

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)

NSwag bietet die folgenden Funktionen:

• Die Möglichkeit, die Swagger-Benutzeroberfläche und den Swagger-Generator zu verwenden.
• Flexible Codegenerierung.

Mit NSwag brauchen Sie keine vorhandene API. Sie können APIs von Drittanbietern verwenden, die Swagger einbinden und eine Client Implementierung generieren. Mit NSwag können Sie den Entwicklungszyklus beschleunigen und sich problemlos an API-Änderungen anpassen.

Registrieren der NSwag-Middleware

Die NSwag-Middleware wird für folgende Zwecke registriert:

• Generieren Sie die Swagger-Spezifikation für die implementierte Web-API.
• Stellen Sie die Swagger-Benutzeroberfläche zum Durchsuchen und Testen die Web-API bereit.

Um NSwag mit ASP.NET Core-Middleware zu verwenden, installieren Sie das NuGet-Paket NSwag.AspNetCore. Dieses Paket enthält die Middleware zum Generieren und Bereitstellen der Swagger-Spezifikation, der Swagger-Benutzeroberfläche (v2 und v3) und der ReDoc-Benutzeroberfläche.

Verwenden Sie einen der folgenden Ansätze, um das NuGet-Paket „NSwag“ zu installieren:

dotnet add TodoApi.csproj package NSwag.AspNetCore

dotnet add TodoApi.csproj package NSwag.AspNetCore

Hinzufügen und Konfigurieren von Swagger-Middleware

Sie können Swagger in Ihrer ASP.NET Core-App hinzufügen und konfigurieren, indem Sie die folgenden Schritte ausführen:

• Registrieren Sie in der Startup.ConfigureServices-Methode die erforderlichen Swagger-Dienste:

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

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

• Aktivieren Sie die Middleware in der Startup.Configure-Methode, um die generierte Swagger-Spezifikation und die Swagger-Benutzeroberfläche zu verarbeiten:

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

• Starten Sie die App. Navigieren Sie zu:
  • http://localhost:<port>/swagger, um die Swagger-Benutzeroberfläche anzuzeigen.
  • http://localhost:<port>/swagger/v1/swagger.json, um die Swagger-Spezifikation anzuzeigen.

Codeerzeugung

Durch die Auswahl einer der folgenden Optionen können Sie die Funktion zur Codegenerierung von NSwag nutzen:

• NSwagStudio: Dies ist eine Windows-Desktop-App zum Generieren von API-Clientcode in C# und TypeScript.
• Die NuGet-Pakete NSwag.CodeGeneration.CSharp oder NSwag.CodeGeneration.TypeScript, um Code innerhalb des Projekts zu generieren.
• NSwag über die Befehlszeile.
• Das NuGet-Paket NSwag.MSBuild.
• Unchase OpenAPI (Swagger) Connected Service: Dies ist ein mit Visual Studio verbundener Dienst zum Generieren von API-Clientcode in C# oder TypeScript. Es werden auch C#-Controller für OpenAPI-Dienste mit NSwag generiert.

Generieren von Code mit NSwagStudio

• Installieren Sie NSwagStudio anhand der Anweisungen im NSwagStudio-GitHub-Repository. Auf der Releaseseite von NSwag können Sie eine XCOPY-Version herunterladen, die ohne Installation und Administratorrechte gestartet werden kann.

• Starten Sie NSwagStudio, und geben Sie die Datei-URL swagger.json in das Textfeld URL zur Spezifizierung des Swaggers ein. Beispiel: http://localhost:44354/swagger/v1/swagger.json.

• Klicken Sie auf die Schaltfläche Lokale Kopie erstellen, um eine JSON-Darstellung Ihrer Swagger-Spezifikation zu generieren.

  

• Aktivieren Sie im Bereich Ausgaben das Kontrollkästchen CSharp-Client. Je nach Ihrem Projekt können Sie auch den TypeScript Client oder CSharp-Web-API-Controller auswählen. Bei der Auswahl des CSharp-Web-API-Controllers erstellt eine Dienstspezifikation den Dienst neu, und dient als eine umgekehrte Generierung.

• Klicken Sie auf Ausgaben generieren, um eine vollständige C#-Clientimplementierung des TodoApi.NSwag-Projekts durchzuführen. Klicken Sie auf die Registerkarte CSharp-Client, damit der generierte Clientcode angezeigt wird:

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

• Kopieren Sie den generierten C#-Code in eine Datei in das Clientprojekt, das die API verwendet.
• Verwendung der Web-API:

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

Anpassen der API-Dokumentation

Swagger umfasst Optionen zum Dokumentieren des Objektmodells, um die Verwendung der Web-API zu vereinfachen.

API-Informationen und -Beschreibung

In der Startup.ConfigureServices-Methode werden Informationen wie Autor, Lizenz und Beschreibung durch die Konfigurationsaktion hinzugefügt, die an die AddSwaggerDocument-Methode übergeben wird:

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

Auf der Swagger-Benutzeroberfläche werden die Versionsinformationen angezeigt:

XML-Kommentare

Um XML-Kommentaren zu aktivieren, führen Sie die folgenden Schritte aus:

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

Datenanmerkungen

Da NSwag Reflection verwendet, und der empfohlene Rückgabetyp für Web-API-Aktionen ActionResult<T> ist, kann nur der von T definierte Rückgabetyp abgeleitet werden. Sie können nicht automatisch andere mögliche Rückgabetypen ableiten.

Betrachten Sie das folgende Beispiel:

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

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

Die vorherige Aktion gibt ActionResult<T> zurück. In der Aktion gibt sie CreatedAtRoute zurück. Da der Controller das Attribut [ApiController] aufweist, ist auch die Antwort BadRequest möglich. Weitere Informationen finden Sie unter Automatische HTTP 400-Antworten. Verwenden Sie Datenanmerkungen, um Clients mitzuteilen, welche HTTP-Statuscodes diese Aktion in der Regel zurückgibt. Markieren Sie die Aktion mit den folgenden Attributen:

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

In ASP.NET Core 2.2 oder höher können Sie stattdessen Konventionen verwenden, um einzelne Aktionen explizit mit [ProducesResponseType] zu ergänzen. Weitere Informationen finden Sie unter Verwenden von Web-API-Konventionen.

Der Swagger-Generator kann diese Aktion nun genau beschreiben, und generierte Clients wissen, was sie beim Aufrufen des Endpunkts empfangen. Es wird empfohlen, alle Aktionen mit diesen Attributen zu markieren.

Richtlinien dazu, welche HTTP-Antworten Ihre API-Aktionen zurückgeben sollten, finden Sie unter RFC 9110: HTTP-Semantik (Abschnitt 9.3. Methodendefinitionen).