OpenAPI belgeleri oluşturma

Paket, Microsoft.AspNetCore.OpenApi ASP.NET Core'da OpenAPI belge oluşturma için yerleşik destek sağlar. Paket aşağıdaki özellikleri sağlar:

• Çalışma zamanında OpenAPI belgeleri oluşturma ve uygulamadaki bir uç nokta üzerinden bunlara erişme desteği.
• Oluşturulan belgenin değiştirilmesine izin veren "transformatör" API'leri desteği.
• Tek bir uygulamadan birden çok OpenAPI belgesi oluşturma desteği.
• tarafından sağlanan JSON şema desteğinden yararlanır System.Text.Json.
• Yerel AoT ile uyumludur.

Paket yükleme

Microsoft.AspNetCore.OpenApi Paketi yükleyin:

Visual Studio

Paket Yöneticisi Konsolu'ndan aşağıdaki komutu çalıştırın:

Install-Package Microsoft.AspNetCore.OpenApi

.NET CLI

Şu komutu çalıştırın:

dotnet add package Microsoft.AspNetCore.OpenApi

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 .

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.

OpenAPI belge adını özelleştirme

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

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

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.

OpenAPI belge erişimini yetkili kullanıcılarla sınırlama

OpenAPI uç noktası varsayılan olarak hiçbir yetkilendirme denetimini etkinleştirmez. Ancak, yetkilendirme denetimleri OpenAPI belgesine uygulanabilir. Aşağıdaki kodda, OpenAPI belgesine erişim rolüne tester sahip olanlarla 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();

Derleme zamanında OpenAPI belgeleri oluşturma

Tipik web uygulamalarında OpenAPI belgeleri çalışma zamanında oluşturulur ve uygulama sunucusuna bir HTTP isteği aracılığıyla sunulur.

Bazı senaryolarda, uygulamanın derleme adımı sırasında OpenAPI belgesini oluşturmak yararlı olur. Bu senaryolar şunlardır:

• Kaynak denetimine kaydedilmiş OpenAPI belgeleri oluşturma.
• Belirtim tabanlı tümleştirme testi için kullanılan OpenAPI belgeleri oluşturma.
• Web sunucusundan statik olarak sunulan OpenAPI belgeleri oluşturma.

Derleme zamanında OpenAPI belgeleri oluşturma desteği eklemek için paketini yükleyin Microsoft.Extensions.ApiDescription.Server :

Visual Studio

Paket Yöneticisi Konsolu'ndan aşağıdaki komutu çalıştırın:

Install-Package Microsoft.Extensions.ApiDescription.Server

.NET CLI

Proje dosyasını içeren dizinde aşağıdaki komutu çalıştırın:

dotnet add package Microsoft.Extensions.ApiDescription.Server

Yükleme sonrasında, bu paket derleme sırasında uygulamayla ilişkili Open API belgelerini otomatik olarak oluşturur ve bunları uygulamanın çıkış dizinine doldurur.

$ dotnet build
$ cat bin/Debug/net9.0/{ProjectName}.json

Derleme zamanı belge oluşturmayı özelleştirme

Oluşturulan Open API dosyasının çıkış dizinini değiştirme

Varsayılan olarak, oluşturulan OpenAPI belgesi uygulamanın çıkış dizinine gönderilir. Yayılan dosyanın konumunu değiştirmek için özelliğinde OpenApiDocumentsDirectory hedef yolu ayarlayın.

<PropertyGroup>
  <OpenApiDocumentsDirectory>./</OpenApiDocumentsDirectory>
</PropertyGroup>

değeri OpenApiDocumentsDirectory proje dosyasına göre çözümlenir. Yukarıdaki değerin ./ kullanılması OpenAPI belgesini proje dosyasıyla aynı dizinde gösterir.

Çıktı dosyasının adını değiştirme

Varsayılan olarak, oluşturulan OpenAPI belgesi uygulamanın proje dosyasıyla aynı ada sahip olur. Yayılan dosyanın adını değiştirmek için özelliğinde bağımsız değişkenini --file-name OpenApiGenerateDocumentsOptions ayarlayın.

<PropertyGroup>
  <OpenApiGenerateDocumentsOptions>--file-name my-open-api</OpenApiGenerateDocumentsOptions>
</PropertyGroup>

Oluşturulacak OpenAPI belgesini seçme

Bazı uygulamalar, bir API'nin çeşitli sürümleri için birden çok OpenAPI belgesi yayacak veya genel ve iç API'ler arasında ayrım yapmak üzere yapılandırılabilir. Varsayılan olarak, derleme zamanı belge oluşturucu bir uygulamada yapılandırılan tüm belgeler için dosyaları yayar. Yalnızca tek bir belge adını yaymak için özelliğinde bağımsız değişkenini --document-name OpenApiGenerateDocumentsOptions ayarlayın.

<PropertyGroup>
  <OpenApiGenerateDocumentsOptions>--document-name v2</OpenApiGenerateDocumentsOptions>
</PropertyGroup>

Derleme zamanı belge oluşturma sırasında çalışma zamanı davranışını özelleştirme

Derleme zamanı OpenAPI belge oluşturma işlevi, uygulamanın giriş noktasını eylemsiz bir sunucu uygulamasıyla başlatarak arka planda çalışır. OpenAPI belgesindeki tüm bilgiler statik olarak çözümlenemediğinden, doğru OpenAPI belgeleri oluşturmak için bu bir gereksinimdir. Uygulamanın giriş noktası çağrıldığından, uygulamaların başlangıcındaki tüm mantık çağrılır. Bu, HIZMETLERI DI kapsayıcısına ekleyen veya yapılandırmadan okuyan kodu içerir. Bazı senaryolarda, uygulamanın giriş noktası derleme zamanı belge oluşturma işleminden çağrılırken çalışacak kod yollarının kısıtlanması gerekir. Bu senaryolar şunlardır:

• Bazı yapılandırma dizelerinden okunmuyor.
• Veritabanıyla ilgili hizmetler kaydedilmiyor.

Bu kod yollarının derleme zamanı oluşturma işlem hattı tarafından çağrılmasını kısıtlamak için, aşağıdaki gibi giriş derlemesinin denetiminin arkasına koşullanabilir:

using System.Reflection;

var builder = WebApplication.CreateBuilder();

if (Assembly.GetEntryAssembly()?.GetName().Name != "GetDocument.Insider")
{
  builder.Services.AddDefaults();
}