openAPI belgelerini kullanma

Yerel geçici test için Swagger kullanıcı arabirimini kullanma

Varsayılan olarak paket, Microsoft.AspNetCore.OpenApi OpenAPI belgesini görselleştirmek veya belgeyle etkileşime girmek için yerleşik destek sağlamaz. OpenAPI belgesini görselleştirmek veya belgeyle etkileşime açmak için kullanılan popüler araçlar arasında Swagger UI ve ReDoc yer alır. Swagger kullanıcı arabirimi ve ReDoc, bir uygulamada çeşitli yollarla tümleştirilebilir. Visual Studio ve Visual Studio Code gibi düzenleyiciler, OpenAPI belgelerinde test için uzantılar ve yerleşik deneyimler sunar.

Paket, Swashbuckle.AspNetCore.SwaggerUi uygulamalarda kullanılmak üzere Swagger kullanıcı arabiriminin web varlıklarından oluşan bir paket sağlar. Bu paket, oluşturulan belge için kullanıcı arabirimini işlemek için kullanılabilir. Bunu yapılandırmak için:

• Swashbuckle.AspNetCore.SwaggerUi paketini yükleyin.
• Swagger-ui ara yazılımını, daha önce kaydedilmiş OpenAPI yoluna bir başvuruyla etkinleştirin.

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

Bilgilerin açığa çıkmasını sınırlama konusunda en iyi güvenlik uygulaması olarak OpenAPI kullanıcı arabirimleri (Swagger UI, ReDoc, Scalar) yalnızca geliştirme ortamlarında etkinleştirilmelidir. Örneğin, bkz. Swagger OAuth 2.0 yapılandırması.

Uygulamayı başlatın ve Swagger kullanıcı arabirimini görüntülemek için adresine gidin https://localhost:<port>/swagger .

Swagger UI URL'sinde uygulamayı, https profilini kullanarak Properties/launchSettings.json otomatik olarak çalıştırmak için:

• launchBrowser etkinleştirildiğini onaylayın (true).
• launchUrl ayarını swagger yapın.

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

Etkileşimli API belgeleri için Scalar kullanma

Skaler , OpenAPI için açık kaynak etkileşimli bir belge kullanıcı arabirimidir. Skaler, ASP.NET Core tarafından sağlanan OpenAPI uç noktasıyla tümleştirilebilir. Scalar'ı yapılandırmak için paketi yükleyin 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();

Uygulamayı başlatın ve Scalar kullanıcı arabirimini görüntülemek için https://localhost:<port>/scalar gidin.

https profili kullanarak Properties/launchSettings.json uygulamasını Scalar KULLANICI Arabirimi URL'sinde otomatik olarak başlatmak için:

• launchBrowser etkinleştirildiğini onaylayın (true).
• launchUrl ayarını scalar yapın.

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

Spektral ile lint tarafından oluşturulan OpenAPI belgeleri

Spectral , açık kaynaklı bir OpenAPI belge linter'idir. Spektral, oluşturulan OpenAPI belgelerinin kalitesini doğrulamak için bir uygulama derlemesine eklenebilir. Spectral'i paket yükleme yol tariflerine göre yükleyin.

Derleme zamanında OpenAPI belgelerinin lintini yapmak için Spectral'den yararlanmak için önce derleme zamanı OpenAPI belge oluşturmayı etkinleştirmek üzere paketi yükleyin Microsoft.Extensions.ApiDescription.Server .

Uygulamanın .csproj dosyasında aşağıdaki özellikleri ayarlayarak derleme zamanında belge oluşturmayı etkinleştirin":

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

Belgeyi oluşturmak için komutunu çalıştırın dotnet build .

dotnet build

Aşağıdaki içeriklere sahip bir .spectral.yml dosya oluşturun.

extends: ["spectral:oas"]

Oluşturulan dosyada komutunu çalıştırın spectral lint .

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)

Ekleme desteği IOpenApiDocumentProvider

OpenAPI belgelerine HTTP isteği bağlamlarının dışında bile program aracılığıyla erişmek için bağımlılık ekleme yoluyla hizmetlerinize ekleyebilirsiniz IOpenApiDocumentProvider .

public class DocumentService
{
    private readonly IOpenApiDocumentProvider _documentProvider;

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

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

Hizmeti DI kapsayıcınıza kaydedin:

builder.Services.AddScoped<DocumentService>();

Bu, istemci SDK'ları oluşturma, arka plan işlemlerinde API sözleşmelerini doğrulama veya belgeleri dış sistemlere dışarı aktarma gibi senaryolara olanak tanır.

Ekleme IOpenApiDocumentProvider desteği .NET 10'da ASP.NET Core'da sunulmuştur. Daha fazla bilgi için bkz. dotnet/aspnetcore #61463.