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.
- Um die Veröffentlichung von Informationen und Sicherheitsrisiken zu minimieren, empfiehlt es sich, Swagger UI nur in Entwicklungsumgebungen zu aktivieren.
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();
app.MapOpenApi();
if (app.Environment.IsDevelopment())
{
app.UseSwaggerUI(options =>
{
options.SwaggerEndpoint("/openapi/v1.json", "v1");
});
}
app.MapGet("/", () => "Hello world!");
app.Run();
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();
app.MapOpenApi();
if (app.Environment.IsDevelopment())
{
app.MapScalarApiReference();
}
app.MapGet("/", () => "Hello world!");
app.Run();
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 Erstellungszeit, 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)
Um zu erfahren, wie man das generierte OpenAPI-Dokument in einer minimalen API in .NET 6, 7 oder 8 verwendet, lesen Sie den Swagger und NSwag Übersicht.
