Verwenden von openAPI-Dokumenten

Swagger UI für lokale Ad-hoc-Tests verwenden

Standardmäßig bietet das Microsoft.AspNetCore.OpenApi-Paket keine integrierte Unterstützung für die Visualisierung des OpenAPI-Dokuments oder die Interaktion damit. Beliebte Tools zum Visualisieren oder Verwenden von OpenAPI-Dokumenten sind Swagger UI und ReDoc. Swagger UI und ReDoc können auf verschiedene Weise in eine App integriert werden. Editoren wie Visual Studio und VS Code bieten Erweiterungen und integrierte Features zum Testen von OpenAPI-Dokumenten.

Das Swashbuckle.AspNetCore.SwaggerUi-Paket enthält einige Webressourcen von Swagger UI für die Verwendung in Apps. Dieses Paket kann zum Rendern einer Benutzeroberfläche für das generierte Dokument verwendet werden. Gehen Sie wie folgt vor, um dies zu konfigurieren:

• Installieren Sie das Swashbuckle.AspNetCore.SwaggerUi-Paket.
• Aktivieren Sie die Swagger-ui-Middleware mit einem Verweis auf die zuvor registrierte OpenAPI-Route.

using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();

    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "v1");
    });

}

app.MapGet("/", () => "Hello world!");

app.Run();

Als bewährte Sicherheitsmaßnahme zur Einschränkung der Offenlegung von Informationen sollten die OpenAPI-Benutzeroberflächen (Swagger UI, ReDoc, Scalar) nur in Entwicklungsumgebungen aktiviert werden. Beispiel: Siehe Swagger OAuth 2.0-Konfiguration.

Starten Sie die App und navigieren Sie zu https://localhost:<port>/swagger, um die Swagger-UI anzuzeigen.

Um die App automatisch unter der Swagger-UI-URL mithilfe des https Profils von Properties/launchSettings.json zu starten:

• Vergewissern Sie sich, dass launchBrowser aktiviert ist (true).
• Legen Sie launchUrl auf swagger fest.

"launchBrowser": true,
"launchUrl": "swagger",

Verwenden von Scalar für die interaktive API-Dokumentation

Scalar ist eine interaktive Open-Source-Dokumentbenutzeroberfläche für OpenAPI. Skalar kann in den von ASP.NET Core bereitgestellten OpenAPI-Endpunkt integriert werden. Um Scalar zu konfigurieren, installieren Sie das Scalar.AspNetCore-Paket.

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;
using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.MapScalarApiReference();
}

app.MapGet("/", () => "Hello world!");

app.Run();

Starten Sie die App, und navigieren Sie zu https://localhost:<port>/scalar/v1, um die Benutzeroberfläche von Scalar anzuzeigen.

So starten Sie die App automatisch an der Scalar-UI-URL unter Verwendung des Profils https von Properties/launchSettings.json.

• Vergewissern Sie sich, dass launchBrowser aktiviert ist (true).
• Legen Sie launchUrl auf scalar/v1 fest.

"launchBrowser": true,
"launchUrl": "scalar/v1",

Mit Linting generierte OpenAPI-Dokumente mit Spectral

Spectral ist ein Open-Source-Dokumentlinter für OpenAPI. Spectral kann in einen App-Build integriert werden, um die Qualität der generierten OpenAPI-Dokumente zu überprüfen. Installieren Sie Spectral gemäß der Anleitung zur Paketinstallation.

Um die Vorteile von Spectral nutzen zu können, installieren Sie das Paket Microsoft.Extensions.ApiDescription.Server, um die OpenAPI-Dokumentgenerierung zur Buildzeit zu ermöglichen.

Aktivieren Sie die Dokumentgenerierung zur Build-Zeit, indem Sie die folgenden Eigenschaften in der .csproj Datei der App festlegen.

<PropertyGroup>
    <OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)</OpenApiDocumentsDirectory>
    <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
</PropertyGroup>

Führen Sie dotnet build aus, um das Dokument zu generieren.

dotnet build

Erstellen Sie eine .spectral.yml-Datei mit dem folgenden Inhalt:

extends: ["spectral:oas"]

Führen Sie spectral lint für die generierte Datei aus.

spectral lint WebMinOpenApi.json
...

The output shows any issues with the OpenAPI document. For example:

```output
1:1  warning  oas3-api-servers       OpenAPI "servers" must be present and non-empty array.
3:10  warning  info-contact           Info object must have "contact" object.                        info
3:10  warning  info-description       Info "description" must be present and non-empty string.       info
9:13  warning  operation-description  Operation "description" must be present and non-empty string.  paths./.get
9:13  warning  operation-operationId  Operation must have "operationId".                             paths./.get

✖ 5 problems (0 errors, 5 warnings, 0 infos, 0 hints)