Microsoft.AspNetCore.OpenApi ile çalışmaya başlama
Önemli
Bu bilgiler, ticari olarak piyasaya sürülmeden önce önemli ölçüde değiştirilebilen bir yayın öncesi ürünle ilgilidir. Burada verilen bilgilerle ilgili olarak Microsoft açık veya zımni hiçbir garanti vermez.
Paket, Microsoft.AspNetCore.OpenApi
ASP.NET Core'da OpenAPI belge oluşturma için yerleşik destek sağlar. Paket:
- Yerel AoT ile uyumludur.
- tarafından
System.Text.Json
sağlanan ON şema desteğinden JSyararlanır. - Oluşturulan belgeleri değiştirmek için transformatörLER API'sini sağlar.
- Tek bir uygulama içinde birden çok OpenAPI belgesini yönetmeyi destekler.
Paket yükleme
Microsoft.AspNetCore.OpenApi
Paketi yükleyin:
Paket Yöneticisi Konsolu'ndan aşağıdaki komutu çalıştırın:
Install-Package Microsoft.AspNetCore.OpenApi -IncludePrerelease
OpenAPI belge oluşturmayı yapılandırma
Aşağıdaki kod:
- OpenAPI hizmetleri ekler.
- OpenAPI belgesini JSON biçiminde görüntülemek için uç noktayı etkinleştirir.
var builder = WebApplication.CreateBuilder();
builder.Services.AddOpenApi();
var app = builder.Build();
app.MapOpenApi();
app.MapGet("/", () => "Hello world!");
app.Run();
Uygulamayı başlatın ve oluşturulan OpenAPI belgesini görüntülemek için adresine gidin https://localhost:<port>/openapi/v1.json
.
Belge adlarının önemi
Bir uygulamadaki her OpenAPI belgesinin benzersiz bir adı vardır. Kaydedilen varsayılan belge adıdır v1
.
builder.Services.AddOpenApi(); // Document name is v1
Belge adı, çağrıya AddOpenApi
parametre olarak geçirilerek değiştirilebilir.
builder.Services.AddOpenApi("internal"); // Document name is internal
Belge adı, OpenAPI uygulamasında çeşitli yerlerde görünür.
Oluşturulan OpenAPI belgesi getirilirken, belge adı istekte documentName
parametre bağımsız değişkeni olarak sağlanır. Aşağıdaki istekler ve internal
belgelerini çözümlerv1
.
GET http://localhost:5000/openapi/v1.json
GET http://localhost:5000/openapi/internal.json
OpenAPI belge oluşturmayı özelleştirme seçenekleri
Aşağıdaki bölümlerde OpenAPI belge oluşturma işleminin nasıl özelleştirileceği gösterilmektedir.
Oluşturulan belgenin OpenAPI sürümünü özelleştirme
Varsayılan olarak, OpenAPI belge oluşturma, OpenAPI belirtiminin v3.0 ile uyumlu bir belge oluşturur. Aşağıdaki kod, OpenAPI belgesinin varsayılan sürümünün nasıl değiştirileceği gösterilmektedir:
builder.Services.AddOpenApi(options =>
{
options.OpenApiVersion = OpenApiSpecVersion.OpenApi2_0;
});
OpenAPI uç noktası yolunu özelleştirme
Varsayılan olarak, çağrı MapOpenApi
yoluyla kaydedilen OpenAPI uç noktası belgeyi /openapi/{documentName}.json
uç noktada kullanıma sunar. Aşağıdaki kodda, OpenAPI belgesinin kaydedildiği yolun nasıl özelleştirileceği gösterilmektedir:
app.MapOpenApi("/openapi/{documentName}/openapi.json");
Not: Yol parametresini uç nokta yolundan documentName
kaldırmak mümkündür ancak önerilmez. documentName
Yol parametresi uç nokta yolundan kaldırıldığında, çerçeve sorgu parametresinden belge adını çözümlemeye çalışır. yolunun veya sorgunun sağlanmaması documentName
beklenmeyen davranışa neden olabilir.
OpenAPI uç noktasını özelleştirme
OpenAPI belgesi bir yol işleyicisi uç noktası aracılığıyla sunulduğundan, standart en düşük uç noktalarda kullanılabilen tüm özelleştirmeler OpenAPI uç noktası tarafından kullanılabilir.
Uç nokta meta verileriyle OpenAPI uç noktalarını özelleştirme
Aşağıdaki listede, oluşturulan OpenAPI belgesini özelleştirmek için kullanılan uç nokta meta verileri gösterilir:
- Özetler: IEndpointSummaryMetadata
- Açıklamaları IEndpointDescriptionMetadata
- Kaynaktan istek gövdesi IAcceptsMetadata
- Yanıt bilgileri IProducesResponseTypeMetadata
- İşlem kimlikleri IEndpointNameMetadata
- OpenAPI etiketleri ITagsMetadata
Uç nokta meta verilerini değiştirerek oluşturulan OpenAPI belgesini özelleştirme hakkında daha fazla bilgi edinmek için bkz . OpenAPI'yi En Az API uygulamalarında kullanma.
OpenAPI belge erişimini yetkili kullanıcılarla sınırlama
OpenAPI uç noktası varsayılan olarak hiçbir yetkilendirme denetimini etkinleştirmez. Ancak, OpenAPI belgesine erişimi sınırlamak mümkündür. Örneğin, aşağıdaki kodda, OpenAPI belgesine erişim rolü olanlarla tester
sınırlıdır:
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.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization(o =>
{
o.AddPolicy("ApiTesterPolicy", b => b.RequireRole("tester"));
});
builder.Services.AddOpenApi();
var app = builder.Build();
app.MapOpenApi()
.RequireAuthorization("ApiTesterPolicy");
app.MapGet("/", () => "Hello world!");
app.Run();
Önbellekle oluşturulan OpenAPI belgesi
OpenAPI belgesi, OpenAPI uç noktasına her istek gönderildiğinde yeniden oluşturulur. Yeniden oluşturma, transformatörlerin dinamik uygulama durumunu çalışmalarına dahil etmelerini sağlar. Örneğin, isteği HTTP bağlamının ayrıntılarıyla yeniden oluşturma. Uygun olduğunda, her HTTP isteğinde belge oluşturma işlem hattının yürütülmesini önlemek için OpenAPI belgesi önbelleğe alınabilir.
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;
var builder = WebApplication.CreateBuilder();
builder.Services.AddOutputCache(options =>
{
options.AddBasePolicy(policy => policy.Expire(TimeSpan.FromMinutes(10)));
});
builder.Services.AddOpenApi();
var app = builder.Build();
app.UseOutputCache();
app.MapOpenApi()
.CacheOutput();
app.MapGet("/", () => "Hello world!");
app.Run();
OpenAPI belge dönüştürücüleri
Bu bölümde, OpenAPI belgelerinin transformatörlerle nasıl özelleştirileceği gösterilmektedir.
OpenAPI belgelerini transformatörlerle özelleştirme
Transformers, OpenAPI belgesini kullanıcı tanımlı özelleştirmelerle değiştirmek için bir API sağlar. Transformatörler aşağıdaki gibi senaryolar için kullanışlıdır:
- Belgedeki tüm işlemlere parametre ekleme.
- Parametreler veya işlemler için açıklamaları değiştirme.
- OpenAPI belgesine üst düzey bilgiler ekleme.
Transformatörler iki kategoriye ayrılır:
- Belge dönüştürücülerinin OpenAPI belgesinin tamamına erişimi vardır. Bunlar belgede genel değişiklikler yapmak için kullanılabilir.
- İşlem transformatörleri her bir işlem için geçerlidir. Her bir işlem, yol ve HTTP yönteminin bir bileşimidir. Bunlar, uç noktalardaki parametreleri veya yanıtları değiştirmek için kullanılabilir.
Transformatörler, nesne üzerindeki çağrı OpenApiOptions
aracılığıyla UseTransformer
belgeye kaydedilebilir. Aşağıdaki kod parçacığında transformatörleri belgeye kaydetmenin farklı yolları gösterilmektedir:
- Temsilci kullanarak bir belge transformatörü kaydedin.
- örneğini kullanarak belge dönüştürücüsünün kaydını
IOpenApiDocumentTransformer
oluşturun. - DI-etkinleştirilmiş
IOpenApiDocumentTransformer
kullanarak bir belge transformatörü kaydedin. - Temsilci kullanarak bir işlem transformatörü kaydedin.
using Microsoft.AspNetCore.OpenApi;
using Microsoft.OpenApi.Models;
var builder = WebApplication.CreateBuilder();
builder.Services.AddOpenApi(options =>
{
options.UseTransformer((document, context, cancellationToken)
=> Task.CompletedTask);
options.UseTransformer(new MyDocumentTransformer());
options.UseTransformer<MyDocumentTransformer>();
options.UseOperationTransformer((operation, context, cancellationToken)
=> Task.CompletedTask);
});
var app = builder.Build();
app.MapOpenApi();
app.MapGet("/", () => "Hello world!");
app.Run();
Transformatörler için yürütme sırası
Transformatörler kayıt temelinde ilk sırada yürütülür. Aşağıdaki kod parçacığında, belge transformatörü işlem transformatörü tarafından yapılan değişikliklere erişime sahiptir:
var builder = WebApplication.CreateBuilder();
builder.Services.AddOpenApi(options =>
{
options.UseOperationTransformer((operation, context, cancellationToken)
=> Task.CompletedTask);
options.UseTransformer((document, context, cancellationToken)
=> Task.CompletedTask);
});
var app = builder.Build();
app.MapOpenApi();
app.MapGet("/", () => "Hello world!");
app.Run();
Belge dönüştürücülerini kullanma
Belge dönüştürücülerinin aşağıdakiler içeren bir bağlam nesnesine erişimi vardır:
- Değiştirilen belgenin adı.
- Bu belgeyle ilişkili liste
ApiDescriptionGroups
. IServiceProvider
Belge oluşturmada kullanılan.
Belge dönüştürücüleri, oluşturulan OpenAPI belgesinin sesini de kapatabilir. Aşağıdaki örnekte, OpenAPI belgesine API hakkında bazı bilgiler ekleyen bir belge dönüştürücü gösterilmektedir.
using Microsoft.Extensions.DependencyInjection;
using Microsoft.AspNetCore.Builder;
var builder = WebApplication.CreateBuilder();
builder.Services.AddOpenApi(options =>
{
options.UseTransformer((document, context, cancellationToken) =>
{
document.Info = new()
{
Title = "Checkout API",
Version = "v1",
Description = "API for processing checkouts from cart."
};
return Task.CompletedTask;
});
});
var app = builder.Build();
app.MapOpenApi();
app.MapGet("/", () => "Hello world!");
app.Run();
Hizmet tarafından etkinleştirilen belge transformatörleri, uygulamayı değiştirmek için DI'den örnekleri kullanabilir. Aşağıdaki örnekte, kimlik doğrulama katmanından IAuthenticationSchemeProvider
hizmeti kullanan bir belge dönüştürücü gösterilmektedir. JWT taşıyıcısı ile ilgili düzenlerin uygulamada kayıtlı olup olmadığını denetler ve bunları OpenAPI belgesinin en üst düzeyine ekler:
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.AddAuthentication().AddJwtBearer();
builder.Services.AddOpenApi(options =>
{
options.UseTransformer<BearerSecuritySchemeTransformer>();
});
var app = builder.Build();
app.MapOpenApi();
app.MapGet("/", () => "Hello world!");
app.Run();
internal sealed class BearerSecuritySchemeTransformer(IAuthenticationSchemeProvider authenticationSchemeProvider) : IOpenApiDocumentTransformer
{
public async Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
{
var authenticationSchemes = await authenticationSchemeProvider.GetAllSchemesAsync();
if (authenticationSchemes.Any(authScheme => authScheme.Name == "Bearer"))
{
var requirements = new Dictionary<string, OpenApiSecurityScheme>
{
["Bearer"] = new OpenApiSecurityScheme
{
Type = SecuritySchemeType.Http,
Scheme = "bearer", // "bearer" refers to the header name here
In = ParameterLocation.Header,
BearerFormat = "Json Web Token"
}
};
document.Components ??= new OpenApiComponents();
document.Components.SecuritySchemes = requirements;
}
}
}
Belge dönüştürücüleri, ilişkilendirildikleri belge örneğine özeldir. Aşağıdaki örnekte bir transformatör:
- Kimlik doğrulamasıyla ilgili gereksinimleri
internal
belgeye kaydeder. - Belgeyi
public
değiştirilmemiş olarak bırakır.
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.AddAuthentication().AddJwtBearer();
builder.Services.AddOpenApi("internal", options =>
{
options.UseTransformer<BearerSecuritySchemeTransformer>();
});
builder.Services.AddOpenApi("public");
var app = builder.Build();
app.MapOpenApi();
app.MapGet("/world", () => "Hello world!")
.WithGroupName("internal");
app.MapGet("/", () => "Hello universe!")
.WithGroupName("public");
app.Run();
internal sealed class BearerSecuritySchemeTransformer(IAuthenticationSchemeProvider authenticationSchemeProvider) : IOpenApiDocumentTransformer
{
public async Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
{
var authenticationSchemes = await authenticationSchemeProvider.GetAllSchemesAsync();
if (authenticationSchemes.Any(authScheme => authScheme.Name == "Bearer"))
{
// Add the security scheme at the document level
var requirements = new Dictionary<string, OpenApiSecurityScheme>
{
["Bearer"] = new OpenApiSecurityScheme
{
Type = SecuritySchemeType.Http,
Scheme = "bearer", // "bearer" refers to the header name here
In = ParameterLocation.Header,
BearerFormat = "Json Web Token"
}
};
document.Components ??= new OpenApiComponents();
document.Components.SecuritySchemes = requirements;
// Apply it as a requirement for all operations
foreach (var operation in document.Paths.Values.SelectMany(path => path.Operations))
{
operation.Value.Security.Add(new OpenApiSecurityRequirement
{
[new OpenApiSecurityScheme { Reference = new OpenApiReference { Id = "Bearer", Type = ReferenceType.SecurityScheme } }] = Array.Empty<string>()
});
}
}
}
}
İşlem transformatörlerini kullanma
İşlemler, OpenAPI belgesindeki HTTP yollarının ve yöntemlerinin benzersiz birleşimleridir. İşlem transformatörleri, bir değişiklik yapıldığında yararlıdır:
- Bir uygulamadaki her uç noktaya yapılmalıdır veya
- Belirli yollara koşullu olarak uygulanır.
İşlem transformatörlerinin aşağıdakiler içeren bir bağlam nesnesine erişimi vardır:
- İşlemin ait olduğu belgenin adı.
ApiDescription
İşlemle ilişkili.IServiceProvider
Belge oluşturmada kullanılan.
Örneğin, aşağıdaki işlem transformatörü belgedeki tüm işlemler tarafından desteklenen bir yanıt durum kodu olarak ekler 500
.
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.AddAuthentication().AddJwtBearer();
builder.Services.AddOpenApi(options =>
{
options.UseOperationTransformer((operation, context, cancellationToken) =>
{
operation.Responses.Add("500", new OpenApiResponse { Description = "Internal server error" });
return Task.CompletedTask;
});
});
var app = builder.Build();
app.MapOpenApi();
app.MapGet("/", () => "Hello world!");
app.Run();
Oluşturulan OpenAPI belgesini kullanma
OpenAPI belgeleri test, belge ve yerel geliştirme için mevcut araçlardan oluşan geniş bir ekosisteme bağlanabilir.
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 VS 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 paketi yükleyin Swashbuckle.AspNetCore.SwaggerUi
.
Swagger-ui ara yazılımını, daha önce kaydedilmiş OpenAPI yoluna bir başvuruyla etkinleştirin. Bilgilerin açığa çıkmasını ve güvenlik açığını sınırlamak için yalnızca geliştirme ortamlarında Swagger kullanıcı arabirimini 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();
app.MapOpenApi();
if (app.Environment.IsDevelopment())
{
app.UseSwaggerUI(options =>
{
options.SwaggerEndpoint("/openapi/v1.json", "v1");
});
}
app.MapGet("/", () => "Hello world!");
app.Run();
Etkileşimli API belgeleri için Skaler 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();
app.MapOpenApi();
if (app.Environment.IsDevelopment())
{
app.MapScalarApiReference();
}
app.MapGet("/", () => "Hello world!");
app.Run();
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.
Spectral'den yararlanmak için derleme zamanı OpenAPI belge oluşturmayı etkinleştirmek için paketi yükleyin Microsoft.Extensions.ApiDescription.Server
.
Uygulamanızı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.
```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)
ASP.NET Core
Geri Bildirim
https://aka.ms/ContentUserFeedback.
Çok yakında: 2024 boyunca, içerik için geri bildirim mekanizması olarak GitHub Sorunları’nı kullanımdan kaldıracak ve yeni bir geri bildirim sistemiyle değiştireceğiz. Daha fazla bilgi için bkz.Gönderin ve geri bildirimi görüntüleyin