Použití dokumentů OpenAPI
Použití uživatelského rozhraní Swagger pro místní ad hoc testování
Ve výchozím nastavení Microsoft.AspNetCore.OpenApi se balíček nedoručuje s integrovanou podporou vizualizace nebo interakce s dokumentem OpenAPI. Mezi oblíbené nástroje pro vizualizaci nebo interakci s dokumentem OpenAPI patří uživatelské rozhraní Swagger a ReDoc. Swagger UI a ReDoc je možné integrovat do aplikace několika způsoby. Editory, jako je Visual Studio a VS Code, nabízejí rozšíření a integrovaná prostředí pro testování v dokumentu OpenAPI.
Balíček Swashbuckle.AspNetCore.SwaggerUi poskytuje sadu webových prostředků uživatelského rozhraní Swagger pro použití v aplikacích. Tento balíček lze použít k vykreslení uživatelského rozhraní pro vygenerovaný dokument. Postup konfigurace:
- Nainstalujte balíček
Swashbuckle.AspNetCore.SwaggerUi. - Povolte middleware swagger-ui s odkazem na trasu OpenAPI zaregistrovanou dříve.
- Pokud chcete omezit zpřístupnění informací a ohrožení zabezpečení, povolte uživatelské rozhraní Swagger pouze ve vývojových prostředích.
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();
Použití scalaru pro interaktivní dokumentaci k rozhraní API
Scalar je opensourcové interaktivní uživatelské rozhraní dokumentu pro OpenAPI. Skalární se dá integrovat s koncovým bodem OpenAPI poskytovaným ASP.NET Core. Pokud chcete nakonfigurovat Scalar, nainstalujte Scalar.AspNetCore balíček.
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();
Vygenerované dokumenty OpenAPI pomocí lintového rozhraní Spectral
Spectral je opensourcový dokument OpenAPI linter. Spectral je možné začlenit do sestavení aplikace a ověřit kvalitu vygenerovaných dokumentů OpenAPI. Nainstalujte aplikaci Spectral podle pokynů pro instalaci balíčku.
Pokud chcete využít výhod Spectral, nainstalujte Microsoft.Extensions.ApiDescription.Server balíček a povolte generování dokumentů OpenAPI v době sestavení.
Povolte generování dokumentů v době sestavení nastavením následujících vlastností v souboru aplikace .csproj :
<PropertyGroup>
<OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)</OpenApiDocumentsDirectory>
<OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
</PropertyGroup>
Spuštěním dotnet build vygenerujte dokument.
dotnet build
Vytvořte .spectral.yml soubor s následujícím obsahem.
extends: ["spectral:oas"]
Spusťte spectral lint vygenerovaný soubor.
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)
