OpenAPI-dokumentumok használata

A Swagger felhasználói felületének használata helyi alkalmi teszteléshez

Alapértelmezés szerint a Microsoft.AspNetCore.OpenApi csomag nem nyújt beépített támogatást az OpenAPI-dokumentum vizualizációjához vagy interakciójához. Az OpenAPI-dokumentum vizualizációjára vagy használatára szolgáló népszerű eszközök közé tartozik Swagger felhasználói felületi és ReDoc. A Swagger felhasználói felülete és a ReDoc többféleképpen integrálható egy alkalmazásba. Az olyan szerkesztők, mint a Visual Studio és a Visual Studio Code, bővítményeket és beépített felületeket kínálnak az OpenAPI-dokumentumok teszteléséhez.

A Swashbuckle.AspNetCore.SwaggerUi csomag a Swagger felhasználói felület webes eszközeinek csomagját biztosítja az alkalmazásokban való használatra. Ez a csomag a létrehozott dokumentum felhasználói felületének megjelenítésére használható. Ennek konfigurálása:

• Telepítse a Swashbuckle.AspNetCore.SwaggerUi csomagot.
• Engedélyezze a swagger-ui köztes szoftvert a korábbanregisztrált OpenAPI-útvonalra mutató hivatkozással.

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

Az információk közzétételének korlátozásával kapcsolatos ajánlott biztonsági gyakorlatként az OpenAPI felhasználói felületeit (Swagger UI, ReDoc, Scalar) csak fejlesztői környezetekben szabad engedélyezni. Lásd például a Swagger OAuth 2.0 konfigurációját.

Indítsa el az alkalmazást, és navigáljon a https://localhost:<port>/swagger-hoz a Swagger felhasználói felületének megtekintéséhez.

Az alkalmazás automatikus indítása a Swagger felhasználói felületÉNEK URL-címén a https következő profillal Properties/launchSettings.json:

• Győződjön meg arról, hogy launchBrowser engedélyezve van (true).
• Állítsa be a launchUrl-t swagger-re.

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

A Scalar használata interaktív API-dokumentációhoz

Scalar egy nyílt forráskódú, interaktív dokumentumfelület az OpenAPI-hoz. A skalár integrálható a ASP.NET Core által biztosított OpenAPI-végponttal. A Scalar konfigurálásához telepítse a Scalar.AspNetCore csomagot.

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

Indítsa el az alkalmazást, és lépjen a https://localhost:<port>/scalar pozícióhoz a Skaláris felhasználói felület megtekintéséhez.

A Scalar felhasználói felület URL-címén lévő alkalmazás automatikus indítása https profil használatával Properties/launchSettings.json:

• Győződjön meg arról, hogy launchBrowser engedélyezve van (true).
• Állítsa be a launchUrl-t scalar-re.

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

Lint által létrehozott OpenAPI-dokumentumok Spectral használatával

Spectral egy nyílt forráskódú OpenAPI dokumentum ellenőrző eszköz. A Spectral beépíthető egy alkalmazás buildjébe a létrehozott OpenAPI-dokumentumok minőségének ellenőrzéséhez. Telepítse a Spectralt a csomag telepítési irányainak megfelelően.

Ahhoz, hogy kihasználhassa a Spectral előnyeit az OpenAPI-dokumentumok buildeléskor történő lintingjéhez, először telepítse a csomagot az Microsoft.Extensions.ApiDescription.Server OpenAPI-dokumentumok buildelési idejének engedélyezéséhez.

A dokumentumlétrehozás engedélyezése létrehozáskor az alkalmazás .csproj fájljában a következő tulajdonságok beállításával:

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

Futtassa dotnet build a dokumentum létrehozásához.

dotnet build

Hozzon létre egy .spectral.yml fájlt a következő tartalommal.

extends: ["spectral:oas"]

Futtasd a spectral lint-t a létrehozott fájlon.

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)

Az injektálási támogatás IOpenApiDocumentProvider

A szolgáltatásokba függőséginjektálással injektálhatja IOpenApiDocumentProvider az OpenAPI-dokumentumokat programozott módon, még a HTTP-kérések környezetén kívül is.

public class DocumentService
{
    private readonly IOpenApiDocumentProvider _documentProvider;

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

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

Regisztrálja a szolgáltatást a DI-tárolóban:

builder.Services.AddScoped<DocumentService>();

Ez olyan forgatókönyveket tesz lehetővé, mint az ügyféloldali SDK-k létrehozása, az API-szerződések érvényesítése háttérfolyamatokban, vagy dokumentumok exportálása külső rendszerekbe.

A .NET 10-ben a ASP.NET Core-ban bevezették az injekciózás IOpenApiDocumentProvider támogatását. További információ: dotnet/aspnetcore #61463.