ASP.NET Core-Web-API-Dokumentation mit Swagger/OpenAPI

  • Artikel

Von Christoph Nienaber und Rico Suter

Bei Swagger (OpenAPI) handelt es sich um eine sprachunabhängige Spezifikation für das Beschreiben von REST-APIs. Sowohl Computer als auch Menschen können so die Funktionen der REST-API verstehen, ohne Direktzugriff auf den Quellcode zu benötigen. Die Hauptziele sind die folgenden:

  • Minimieren des Arbeitsaufwands, der zum Verbinden von getrennten Diensten erforderlich ist
  • Verringern des Zeitaufwands, der für die genaue Dokumentation eines Diensts erforderlich ist

Die zwei OpenAPI-Hauptimplementierungen für .NET sind Swashbuckle und NSwag. Weitere Informationen finden Sie in den folgenden Artikeln:

OpenAPI vs. Swagger

Das Swagger-Projekt wurde 2015 an die OpenAPI-Initiative übergeben. Dort wird es nun als „OpenAPI“ bezeichnet. Beide Namen können austauschbar verwendet werden. OpenAPI bezieht sich jedoch auf die Spezifikation. Swagger bezieht sich auf die Familie der Open-Source- und kommerziellen Produkte von SmartBear, die die OpenAPI-Spezifikation verwenden. Verwandte Open-Source-Produkte wie OpenAPIGenerator gehören auch zur Swagger-Familie, obwohl sie nicht von SmartBear veröffentlicht wurden.

Kurz gesagt:

  • OpenAPI ist eine Spezifikation.
  • Swagger ist ein Tool, das die OpenAPI-Spezifikation verwendet. Beispiele sind OpenAPIGenerator und SwaggerUI.

OpenAPI-Spezifikation (openapi.json)

Die OpenAPI-Spezifikation ist ein Dokument, in dem die Funktionen Ihrer API beschrieben werden. Das Dokument basiert auf der XML-Datei und den Attributanmerkungen innerhalb der Controller und Modelle. Es handelt sich dabei um den Hauptteil des OpenAPI-Flows, und dieser wird für die Steuerung von Tools wie SwaggerUI verwendet. Standardmäßig heißt sie openapi.json. Hier finden Sie ein Beispiel der OpenAPI-Spezifikation, das aus Gründen der Übersichtlichkeit reduziert wurde:

{
  "openapi": "3.0.1",
  "info": {
    "title": "API V1",
    "version": "v1"
  },
  "paths": {
    "/api/Todo": {
      "get": {
        "tags": [
          "Todo"
        ],
        "operationId": "ApiTodoGet",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              },
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              },
              "text/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        …
      }
    },
    "/api/Todo/{id}": {
      "get": {
        …
      },
      "put": {
        …
      },
      "delete": {
        …
      }
    }
  },
  "components": {
    "schemas": {
      "ToDoItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int32"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "isCompleted": {
            "type": "boolean"
          }
        },
        "additionalProperties": false
      }
    }
  }
}

Swagger-Benutzeroberfläche

Die Swagger-Benutzeroberfläche ist eine webbasierte Benutzeroberfläche, die anhand der generierten OpenAPI-Spezifikation Informationen über den Dienst bereitstellt. Swashbuckle und NSwag enthalten eine eingebettete Version der Swagger-Benutzeroberfläche, sodass diese in Ihrer ASP.NET Core-App mithilfe eines Registrierungsaufrufs für die Middleware gehostet werden kann. Die Webbenutzeroberfläche sieht folgendermaßen aus:

Swagger-Benutzeroberfläche

Jede öffentliche Aktionsmethode in Ihren Controllern kann über die Benutzeroberfläche getestet werden. Klicken Sie auf einen Methodennamen, um den Abschnitt zu erweitern. Fügen Sie die erforderlichen Parameter hinzu, und klicken Sie auf Probieren Sie es aus! .

Beispiel für einen Swagger-GET-Test

Hinweis

Die für den Screenshot verwendete Version der Swagger-Benutzeroberfläche ist Version 2. Ein Beispiel für Version 3 finden Sie unter Pet store example (Beispiel für eine Tierhandlung).

Schützen von Endpunkten der Swagger-Benutzeroberfläche

Rufen Sie MapSwagger().RequireAuthorization auf, um die Endpunkte der Swagger-Benutzeroberfläche zu schützen. Im folgenden Beispiel werden die Swagger-Endpunkte geschützt:

using System.Security.Claims;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

builder.Services.AddAuthorization();
builder.Services.AddAuthentication("Bearer").AddJwtBearer();

var app = builder.Build();

  if (app.Environment.IsDevelopment())
  {
    app.UseSwagger();
    app.UseSwaggerUI();
  }

app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapSwagger().RequireAuthorization();

app.MapGet("/", () => "Hello, World!");
app.MapGet("/secret", (ClaimsPrincipal user) => $"Hello {user.Identity?.Name}. My secret")
    .RequireAuthorization();

app.MapGet("/weatherforecast", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast")
.WithOpenApi();

app.Run();

internal record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

Im vorherigen Code benötigt der /weatherforecast-Endpunkt keine Autorisierung, die Swagger-Endpunkte jedoch schon.

Die folgende cURL übergibt ein JWT-Token, um den Endpunkt der Swagger-Benutzeroberfläche zu testen:

curl -i -H "Authorization: Bearer {token}" https://localhost:{port}/swagger/v1/swagger.json

Weitere Informationen zum Testen mit JWT-Token finden Sie unter Generieren von Token mit „dotnet user-jwts“.

Generieren Sie eine XML-Dokumentationsdatei zur Kompilierzeit.

Weitere Informationen finden Sie unter GenerateDocumentationFile.

Nächste Schritte

Von Christoph Nienaber und Rico Suter

Bei Swagger (OpenAPI) handelt es sich um eine sprachunabhängige Spezifikation für das Beschreiben von REST-APIs. Sowohl Computer als auch Menschen können so die Funktionen der REST-API verstehen, ohne Direktzugriff auf den Quellcode zu benötigen. Die Hauptziele sind die folgenden:

  • Minimieren des Arbeitsaufwands, der zum Verbinden von getrennten Diensten erforderlich ist
  • Verringern des Zeitaufwands, der für die genaue Dokumentation eines Diensts erforderlich ist

Die zwei OpenAPI-Hauptimplementierungen für .NET sind Swashbuckle und NSwag. Weitere Informationen finden Sie in den folgenden Artikeln:

OpenAPI vs. Swagger

Das Swagger-Projekt wurde 2015 an die OpenAPI-Initiative übergeben. Dort wird es nun als „OpenAPI“ bezeichnet. Beide Namen können austauschbar verwendet werden. OpenAPI bezieht sich jedoch auf die Spezifikation. Swagger bezieht sich auf die Familie der Open-Source- und kommerziellen Produkte von SmartBear, die die OpenAPI-Spezifikation verwenden. Verwandte Open-Source-Produkte wie OpenAPIGenerator gehören auch zur Swagger-Familie, obwohl sie nicht von SmartBear veröffentlicht wurden.

Kurz gesagt:

  • OpenAPI ist eine Spezifikation.
  • Swagger ist ein Tool, das die OpenAPI-Spezifikation verwendet. Beispiele sind OpenAPIGenerator und SwaggerUI.

OpenAPI-Spezifikation (openapi.json)

Die OpenAPI-Spezifikation ist ein Dokument, in dem die Funktionen Ihrer API beschrieben werden. Das Dokument basiert auf der XML-Datei und den Attributanmerkungen innerhalb der Controller und Modelle. Es handelt sich dabei um den Hauptteil des OpenAPI-Flows, und dieser wird für die Steuerung von Tools wie SwaggerUI verwendet. Standardmäßig heißt sie openapi.json. Hier finden Sie ein Beispiel der OpenAPI-Spezifikation, das aus Gründen der Übersichtlichkeit reduziert wurde:

{
  "openapi": "3.0.1",
  "info": {
    "title": "API V1",
    "version": "v1"
  },
  "paths": {
    "/api/Todo": {
      "get": {
        "tags": [
          "Todo"
        ],
        "operationId": "ApiTodoGet",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              },
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              },
              "text/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        …
      }
    },
    "/api/Todo/{id}": {
      "get": {
        …
      },
      "put": {
        …
      },
      "delete": {
        …
      }
    }
  },
  "components": {
    "schemas": {
      "ToDoItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int32"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "isCompleted": {
            "type": "boolean"
          }
        },
        "additionalProperties": false
      }
    }
  }
}

Swagger-Benutzeroberfläche

Die Swagger-Benutzeroberfläche ist eine webbasierte Benutzeroberfläche, die anhand der generierten OpenAPI-Spezifikation Informationen über den Dienst bereitstellt. Swashbuckle und NSwag enthalten eine eingebettete Version der Swagger-Benutzeroberfläche, sodass diese in Ihrer ASP.NET Core-App mithilfe eines Registrierungsaufrufs für die Middleware gehostet werden kann. Die Webbenutzeroberfläche sieht folgendermaßen aus:

Swagger-Benutzeroberfläche

Jede öffentliche Aktionsmethode in Ihren Controllern kann über die Benutzeroberfläche getestet werden. Klicken Sie auf einen Methodennamen, um den Abschnitt zu erweitern. Fügen Sie die erforderlichen Parameter hinzu, und klicken Sie auf Probieren Sie es aus! .

Beispiel für einen Swagger-GET-Test

Hinweis

Die für den Screenshot verwendete Version der Swagger-Benutzeroberfläche ist Version 2. Ein Beispiel für Version 3 finden Sie unter Pet store example (Beispiel für eine Tierhandlung).

Nächste Schritte