ASP.NET Core API uygulamalarında OpenAPI desteği

ASP.NET Core, denetleyici tabanlı ve minimum API uygulamalarında OpenAPI belgelerinin oluşturulmasını destekler. OpenAPI belirtimi, HTTP API'lerini belgeleme için programlama dilinden bağımsız bir standarttır. Bu standart, ASP.NET Core uygulamalarında yerleşik API'ler ve açık kaynak kitaplıkların birleşimi aracılığıyla desteklenir. Bir uygulamada OpenAPI tümleştirmenin üç temel yönü vardır:

• Uygulamadaki uç noktalar hakkında bilgi oluşturma.
• Bilgileri OpenAPI şemasıyla eşleşen bir biçimde toplama.
• Oluşturulan OpenAPI belgesini görsel kullanıcı arabirimi veya serileştirilmiş bir dosya aracılığıyla ortaya çıkarma.

ASP.NET Core uygulamaları, paket aracılığıyla Microsoft.AspNetCore.OpenApi bir uygulamadaki uç noktalar hakkında bilgi oluşturmak için yerleşik destek sağlar.

Aşağıdaki kod, ASP.NET Core minimal web API'si şablonu tarafından oluşturulur ve OpenAPI kullanır:

using Microsoft.AspNetCore.OpenApi;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weatherforecast", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateTime.Now.AddDays(index),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast");

app.Run();

internal record WeatherForecast(DateTime Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

Yukarıdaki vurgulanan kodda:

• AddOpenApi OpenAPI belge oluşturma için gereken hizmetleri uygulamanın DI kapsayıcısına kaydeder.
• MapOpenApi , JSON olarak seri hale getirilmiş OpenAPI belgesini görüntülemek için uygulamaya bir uç nokta ekler. OpenAPI uç noktası, hassas bilgilerin açığa çıkma riskini en aza indirmek ve üretimdeki güvenlik açıklarını azaltmak için geliştirme ortamıyla sınırlıdır.

Microsoft.AspNetCore.OpenApi NuGet paketi

Paket Microsoft.AspNetCore.OpenApi 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.

Paketi kullanmak Microsoft.AspNetCore.OpenApi için bir proje dosyasına PackageReference olarak ekleyin:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

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

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.*-*" />
    <PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="9.0.*-*">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
  </ItemGroup>

</Project>

Paket hakkında Microsoft.AspNetCore.OpenApi daha fazla bilgi edinmek için bkz . OpenAPI belgeleri oluşturma.

Microsoft.Extensions.ApiDescription.Server NuGet paketi

Paket, Microsoft.Extensions.ApiDescription.Server derleme zamanında OpenAPI belgeleri oluşturmak ve bunları serileştirmek için destek sağlar.

kullanmak Microsoft.Extensions.ApiDescription.Serveriçin bunu bir proje dosyasına PackageReference olarak ekleyin. Derleme zamanında belge oluşturma özelliği ayarlanarak OpenApiGenerateDocuments etkinleştirilir. Varsayılan olarak, oluşturulan OpenAPI belgesi dizine obj kaydedilir, ancak özelliğini ayarlayarak çıkış dizinini OpenApiDocumentsDirectory özelleştirebilirsiniz.

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

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

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.*-*" />
    <PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="9.0.*-*">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
  </ItemGroup>

</Project>

API v. API işlemi v. API uç noktası

Aşağıdaki bölümlerde, ASP.NET Core ve OpenAPI belgeleri bağlamında API, API uç noktası ve API işlemi arasındaki farklar açıklanmaktadır.

API (Uygulama Programlama Arabirimi)

API, yazılım uygulamaları oluşturmaya ve bunlarla etkileşim kurmaya yönelik bir dizi kural ve protokoldür. Farklı yazılım bileşenlerinin nasıl iletişim kurması gerektiğini tanımlar. Genel web geliştirmede "API", genellikle HTTP üzerinden işlevselliği kullanıma sunan bir web hizmetini ifade eder.

ASP.NET Core'da bir API genellikle gelen HTTP isteklerini işleyen ve yanıtları döndüren denetleyiciler veya en düşük API'ler kullanılarak oluşturulur.

ASP.NET Core'un iç adlandırma kuralları bazen "API" özelliğini farklı kullanır. Örneğin , API Gezgini'nde "ApiDescription" aslında tam API hizmeti yerine api işlemini temsil eder. Bu ayrım iç adlandırma kurallarını yansıtır ve bazen burada kullanılan daha geniş tanımdan farklıdır.

API Gezgini hakkında daha fazla bilgi için bkz. ASP.NET Core'da ApiExplorer'a giriş .

API İşlemi

API işlemi, BIR API'nin sağladığı belirli bir eylemi veya özelliği temsil eder. ASP.NET Core'da bu, aşağıdakilere karşılık gelir:

• MVC stili API'lerde denetleyici eylem yöntemleri
• Minimal API'lerde rota işleyicileri

Her işlem HTTP yöntemi (GET, POST, PUTvb.), yolu, parametreleri ve yanıtları ile tanımlanır.

API Uç Noktası

API uç noktası belirli bir URL'dir:

• Bu, API tarafından kullanıma sunulan belirli bir kaynağı veya işlevselliği temsil eder.
• Belirli bir API işlemiyle etkileşim kurmak için istemcinin http isteği göndermesi gereken tam adresi sağlar.

Uç nokta, DESTEKLENEN HTTP yöntemleriyle birlikte API'nin temel URL'si ile istenen kaynağın belirli bir yolunun birleşimidir:

• Denetleyici tabanlı API'ler için uç noktalar, yol şablonunu denetleyici ve eylemle birleştirir.
• Minimum API'ler için uç noktalar , vb. ile app.MapGet()app.MapPost()açıkça tanımlanır.

Örneğin, api/products/{id} aşağıdaki işlemleri destekleyen uç nokta:

• GET /api/products/{id}
• PUT /api/products/{id}
• PATCH /api/products/{id}
• Delete /api/products/{id}
• HEAD /api/products/{id}

Uç noktalar genellikle sorgu parametrelerini içerir, örneğin, GET /api/products?category=electronics&sort=price

OpenAPI Belgeleri

OpenAPI bağlamında, belgelerde API'nin tüm uç noktaları ve işlemleri de dahil olmak üzere bir bütün olarak açıklanmaktadır. OpenAPI, API'leri belgeleyerek geliştiricilerin bunlarla nasıl etkileşim kuracaklarını daha kolay anlamasını sağlayan yapılandırılmış bir yol sağlar.

API İşlemleri, OpenAPI belgelerinin birincil odağıdır. OpenAPI belirtimi belgeleri yollara (uç noktalara) göre gruplandırılmış işlemlere göre düzenler. Her işlem parametreler, istek gövdeleri, yanıtlar ve daha fazlası gibi ayrıntılarla açıklanır. Bu yapılandırılmış biçim, araçların otomatik olarak istemci kitaplıkları, sunucu saptamaları ve etkileşimli belgeler oluşturmasına olanak tanır.

OpenAPI belgesinde:

• Belgenin tamamı API'yi bir bütün olarak açıklar
• Her yol öğesi (gibi /api/products/{id}) bir uç noktayı temsil eder
• Her yolun altında HTTP yöntemleri (GET, POST, PUTvb.) işlemleri tanımlar
• Her işlem parametreler, istek gövdesi, yanıtlar vb. hakkındaki ayrıntıları içerir.

OpenAPI JSON biçimindeki örnek:

json{
  "paths": {
    "/api/products/{id}": {  // This is the endpoint
      "get": {  // This is the operation
        "summary": "Get a product by ID",
        "parameters": [...],
        "responses": {...}
      },
      "put": {  // Another operation on the same endpoint
        "summary": "Update a product",
        "parameters": [...],
        "responses": {...}
      }
    }
  }
}

API, API işlemi ve API uç noktası karşılaştırması

Aşağıdaki tabloda API, API işlemi ve API uç noktası arasındaki farklar özetlemektedir:

Konsept	API İşlemi	API Uç Noktası
Tanım	API eyleminin mantıksal açıklaması: yöntem + yol + davranış	İstekleri dinleyen gerçek yapılandırılmış HTTP yolu
Düzeyi	Kavramsal, hangi eylemin gerçekleşebileceği	Somut, hangi URL ve yöntem eşleştirildi?
Bağlı	OpenAPI API tasarımı/belirtimi	Çalışma zamanında ASP.NET Core yönlendirmesi
Açıklar	API'nin yaptığı şey( örneğin, "ürün oluşturma"	Nerede ve nasıl çağrılır, örneğin POST https://localhost:7099/api/products, POST https://contoso.com/api/products
ASP.NET Core'da	Yönlendirme çözümlenmeden önce denetleyici eylemleri veya Minimum API yöntemleri	Çalışma zamanında çözümlenen uç nokta nesneleri

GitHub'da ASP.NET Core OpenAPI kaynak kodu

• AddOpenApi
• OpenApiDocumentService
• OpenApiOptions

Ek Kaynaklar

• Minimum API'lerde kimlik doğrulaması ve yetkilendirme