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 aReDoc. Swagger UI a ReDoc je možné integrovat do aplikace několika způsoby. Editory, jako jsou Visual Studio a Visual Studio Code, nabízejí rozšíření a předdefinované 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.

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

Osvědčeným postupem zabezpečení při omezení zpřístupnění informací by měla být uživatelská rozhraní OpenAPI (Swagger UI, ReDoc, Scalar) povolená pouze ve vývojových prostředích. Viz například konfigurace Swagger OAuth 2.0.

Spusťte aplikaci a přejděte na https://localhost:<port>/swagger, abyste zobrazili uživatelské rozhraní Swagger.

Automatické spuštění aplikace na adrese URL uživatelského rozhraní Swagger pomocí https profilu Properties/launchSettings.json:

• Potvrďte, že launchBrowser je povolená (true).
• Nastavte launchUrl na swagger.

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

Použití scalaru pro interaktivní dokumentaci k rozhraní API

Scalar je opensourcové interaktivní uživatelské rozhraní dokumentu pro OpenAPI. Scalar lze 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();

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

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

app.Run();

Spusťte aplikaci a přejděte na https://localhost:<port>/scalar, abyste si prohlédli skalární uživatelské rozhraní.

Pro automatické spuštění aplikace na URL adrese uživatelského rozhraní Scalar pomocí profilu https od Properties/launchSettings.json:

• Potvrďte, že launchBrowser je povolená (true).
• Nastavte launchUrl na scalar.

"launchBrowser": true,
"launchUrl": "scalar",

Vygenerované dokumenty OpenAPI pomocí lintového rozhraní Spectral

Spectral je open-source linter pro dokumenty OpenAPI. 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 funkce Spectral pro lintování dokumentů OpenAPI v době sestavení, nejprve nainstalujte balíček a povolte Microsoft.Extensions.ApiDescription.Server 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 na vygenerovaném souboru.

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)

Podpora vkládání IOpenApiDocumentProvider

Do služeb můžete vkládat IOpenApiDocumentProvider prostřednictvím injektáže závislostí pro přístup k dokumentům OpenAPI prostřednictvím kódu programu, a to i mimo kontexty požadavků HTTP.

public class DocumentService
{
    private readonly IOpenApiDocumentProvider _documentProvider;

    public DocumentService(IOpenApiDocumentProvider documentProvider)
    {
        _documentProvider = documentProvider;
    }

    public async Task<OpenApiDocument> GetApiDocumentAsync()
    {
        return await _documentProvider.GetOpenApiDocumentAsync("v1");
    }
}

Zaregistrujte službu v kontejneru DI:

builder.Services.AddScoped<DocumentService>();

To umožňuje scénáře, jako je generování klientských sad SDK, ověřování kontraktů rozhraní API v procesech na pozadí nebo export dokumentů do externích systémů.

Podpora vkládání IOpenApiDocumentProvider byla zavedena v ASP.NET Core v .NET 10. Další informace najdete v tématu dotnet/aspnetcore #61463.