Korzystanie z dokumentów openAPI

Użyj Swagger UI do lokalnego testowania ad hoc

Domyślnie Microsoft.AspNetCore.OpenApi pakiet nie jest dostarczany z wbudowaną obsługą wizualizacji ani interakcji z dokumentem OpenAPI. Popularne narzędzia do wizualizacji lub interakcji z dokumentem OpenAPI to Swagger UI i ReDoc. Interfejs użytkownika programu Swagger i narzędzie ReDoc można zintegrować w aplikacji na kilka sposobów. Edytory, takie jak Visual Studio i Visual Studio Code, oferują rozszerzenia i wbudowane środowiska do testowania w oparciu o dokument OpenAPI.

Pakiet Swashbuckle.AspNetCore.SwaggerUi zawiera zestaw zasobów webowych interfejsu użytkownika Swagger do wykorzystania w aplikacjach. Ten pakiet może służyć do renderowania interfejsu użytkownika wygenerowanego dokumentu. Aby to skonfigurować:

• Zainstaluj pakiet Swashbuckle.AspNetCore.SwaggerUi.
• Włącz oprogramowanie pośredniczące swagger-ui z odwołaniem do trasy OpenAPI zarejestrowanej wcześniej.

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

W ramach najlepszych praktyk w zakresie zabezpieczeń dotyczących ograniczania ujawniania informacji interfejsy użytkownika OpenAPI (Swagger UI, ReDoc, Scalar) powinny być włączane tylko w środowiskach deweloperskich. Zobacz na przykład konfigurację Swagger OAuth 2.0.

Uruchom aplikację i przejdź do https://localhost:<port>/swagger, aby wyświetlić interfejs Swagger UI.

Aby automatycznie uruchomić aplikację pod adresem URL interfejsu użytkownika Swagger przy użyciu https profilu Properties/launchSettings.json:

• Upewnij się, że launchBrowser włączono (true).
• Ustaw opcję launchUrl na swagger.

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

Użyj Scalar do interaktywnej dokumentacji interfejsu API

Skalar to interaktywny interfejs użytkownika dokumentu typu open source dla interfejsu OpenAPI. Scalar może integrować się z punktem końcowym interfejsu OpenAPI umożliwianym przez platformę ASP.NET Core. Aby skonfigurować Scalar, zainstaluj pakiet Scalar.AspNetCore.

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

Uruchom aplikację i przejdź do https://localhost:<port>/scalar, aby wyświetlić interfejs użytkownika skalarny.

Aby automatycznie uruchomić aplikację w interfejsie użytkownika Scalar na adresie URL używając profilu https z Properties/launchSettings.json:

• Upewnij się, że launchBrowser włączono (true).
• Ustaw opcję launchUrl na scalar.

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

Lint wygenerowane dokumenty OpenAPI za pomocą Spectral

Spectral to narzędzie open source do sprawdzania dokumentów OpenAPI. Spectral można włączyć do kompilacji aplikacji, aby zweryfikować jakość wygenerowanych dokumentów OpenAPI. Zainstaluj Spectral zgodnie ze wskazówkami instalacji pakietu.

Aby skorzystać z narzędzia Spectral w celu lintowania dokumentów OpenAPI w czasie kompilacji, najpierw zainstaluj pakiet Microsoft.Extensions.ApiDescription.Server, aby włączyć generowanie dokumentów OpenAPI.

Włącz generowanie dokumentów w czasie kompilacji, ustawiając następujące właściwości w pliku aplikacji .csproj ":

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

Uruchom polecenie dotnet build , aby wygenerować dokument.

dotnet build

.spectral.yml Utwórz plik z następującą zawartością.

extends: ["spectral:oas"]

Uruchom polecenie spectral lint w wygenerowanych plikach.

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)

Obsługa wstrzykiwania IOpenApiDocumentProvider

W celu programowego uzyskiwania dostępu do dokumentów OpenAPI można wprowadzać IOpenApiDocumentProvider do usług za pomocą iniekcji zależności, nawet poza kontekstami żądań HTTP.

public class DocumentService
{
    private readonly IOpenApiDocumentProvider _documentProvider;

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

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

Zarejestruj usługę w kontenerze DI:

builder.Services.AddScoped<DocumentService>();

Umożliwia to scenariusze, takie jak generowanie zestawów SDK klienta, weryfikowanie kontraktów interfejsu API w procesach w tle lub eksportowanie dokumentów do systemów zewnętrznych.

Obsługa wstrzykiwania IOpenApiDocumentProvider została wprowadzona w programie ASP.NET Core na platformie .NET 10. Aby uzyskać więcej informacji, zobacz dotnet/aspnetcore #61463.