C# Academy · Ders

OpenAPI Belgeleri Oluşturma

Makine tarafından okunabilir API özellikleri üretin.

OpenAPI Belgeleri Oluşturma, CoddyKit'te ücretsiz bir C# Academy dersidir. Bu, 4 dersinin 3. dersidir. Aşağıdan dersin tamamını ücretsiz okuyabilir, sonra tarayıcıda yerleşik kod editörü ve 7/24 yapay zeka koçu ile uygulamalı olarak pratik yapabilirsin. Bu, C# Academy öğrenme yolunun bir parçasıdır ve ilerlemeniz web ve CoddyKit uygulaması arasında senkronize olur. C# Academy kursu toplamda 4 dersten oluşur.

OpenAPI Nedir?

OpenAPI, bir HTTP API'sinin standart ve makine tarafından okunabilir açıklamasıdır. Bu açıklamadan belgeler, istemci SDK'ları ve sınama araçları oluşturabilirsiniz.

.NET 9, yerleşik OpenAPI belgesi oluşturma özelliğiyle birlikte gelir ve birçok uygulamada eski Swashbuckle bağımlılığının yerini alır.

// OpenAPI document = JSON describing paths, schemas, params

Microsoft.AspNetCore.OpenApi Paketi

Yerleşik destek Microsoft.AspNetCore.OpenApi içinde bulunur. .NET 9 şablonlarında bu pakete zaten başvurulur.

dotnet add package Microsoft.AspNetCore.OpenApi

AddOpenApi

Belge oluşturucuyu hizmet yapılandırmanızda AddOpenApi ile kaydedin.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

MapOpenApi

MapOpenApi, oluşturulan belgeyi bir uç noktada kullanıma sunar. Varsayılan olarak belgeyi /openapi/v1.json adresinde sunar.

var app = builder.Build();

app.MapOpenApi();   // GET /openapi/v1.json

app.Run();

Yalnızca Geliştirmeyle Sınırlandırma

Üretim ortamında API yüzeyinizi açığa çıkarmamak için belgeyi yalnızca geliştirme ortamında kullanıma sunmak yaygın bir uygulamadır.

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

Uç Noktaları Açıklama

OpenAPI üst verileri kodunuzdan zenginleştirilir. Minimal API uç noktalarında WithSummary, WithDescription ve WithTags kullanın.

app.MapGet("/products/{id}", (int id) => Results.Ok())
   .WithSummary("Get a product by id")
   .WithDescription("Returns a single product or 404.")
   .WithTags("Products");

Yanıtları Belgeleme

Belgenin bunları doğru şekilde listelemesi için yanıt türlerini ve durum kodlarını bildirin.

app.MapGet("/products/{id}", (int id) => Results.Ok())
   .Produces<Product>(StatusCodes.Status200OK)
   .Produces(StatusCodes.Status404NotFound);

Belge Dönüştürücüleri

Tüm belgeyi (başlık, sürüm ve sunucular gibi) AddOpenApi'ye geçirilen bir belge dönüştürücüsü ile özelleştirin.

builder.Services.AddOpenApi(options =>
{
    options.AddDocumentTransformer((doc, ctx, ct) =>
    {
        doc.Info.Title = "Catalog API";
        doc.Info.Version = "1.0";
        return Task.CompletedTask;
    });
});

İşlem Dönüştürücüleri

Bir işlem dönüştürücüsü, tek tek işlemleri değiştirir; örneğin her uç noktaya ortak bir üst bilgi parametresi ekler.

options.AddOperationTransformer((operation, ctx, ct) =>
{
    operation.Responses.TryAdd("500",
        new OpenApiResponse { Description = "Server error" });
    return Task.CompletedTask;
});

Arayüz Ekleme

Yerleşik oluşturucu JSON belgesini üretir ancak bir arayüz sağlamaz. Bunu Scalar veya Swagger UI gibi bir görüntüleyiciyle birlikte kullanın.

// dotnet add package Scalar.AspNetCore
app.MapOpenApi();
app.MapScalarApiReference();  // interactive docs at /scalar/v1

Derleme Zamanında Oluşturma

OpenAPI dosyasını çalışan bir sunucu olmadan derleme sırasında, Microsoft.Extensions.ApiDescription.Server araçlarını kullanarak oluşturabilirsiniz. Bu, CI istemci oluşturma işlemleri için kullanışlıdır.

// .csproj
// <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
// produces obj/<App>.json on build

Kısa Kontrol

.NET 9 OpenAPI temellerini doğrulayın.

Özet

OpenAPI belgeleri oluşturdunuz:

AddOpenApi() oluşturucuyu kaydeder; MapOpenApi() JSON'u sunar.
Uç noktaları WithSummary, Produces ve etiketlerle zenginleştirin.
Belge ve işlem dönüştürücüleri çıktıyı özelleştirir.
Etkileşimli bir görünüm için Scalar veya Swagger UI ile birlikte kullanın.

Sırada: sürümlü API'leri belgeleme.

Sıkça Sorulan Sorular

“OpenAPI Belgeleri Oluşturma” dersi ücretsiz mi?

Evet — “OpenAPI Belgeleri Oluşturma” dersin tüm metni burada web'de ücretsiz olarak okunabilir. Etkileşimli olarak pratik yapmak (yerleşik kod editörü ve 7/24 yapay zeka koçu) ve C# Academy kursunun geri kalanını açmak için CoddyKit PRO'ya yükselt. C# Academy kursu toplamda 4 dersten oluşur.

“OpenAPI Belgeleri Oluşturma” dersinde ne öğreneceğim?

Makine tarafından okunabilir API özellikleri üretin. C# Academy ile uygulamalı kodu tarayıcıda doğrudan çalıştırarak pratik yaparsın ve 7/24 yapay zeka koçu dersi çalışırken sorularını yanıtlar.

C# Academy öğrenmeye başlamak için deneyim gerekli mi?

Önceden deneyim gerekmez. CoddyKit'te C# Academy, başlangıçtan ileri seviyeye kadar yapılandırıldığı için buradan başlayabilir veya başından başlayıp kendi hızında ilerleme yapabilirsin. Bu, 4 dersinin 3. dersidir.

“OpenAPI Belgeleri Oluşturma” dersi ne kadar sürer?

Çoğu CoddyKit dersi yaklaşık 5–10 dakika sürer. Her biri kısa ve etkileşimli olduğu için sabit ilerleme yaparsın ve web ile uygulama arasında tam olarak bıraktığın yerden devam edebilirsin.

Bu C# Academy dersinde kod yazıp çalıştırabilir miyim?

Evet. Her C# Academy dersi yerleşik bir kod editörü içerir, bu sayede tarayıcıda gerçek kod yazıp çalıştırabilir ve anlık yapay zeka geri bildirimi alırsın — yerel kurulum gerekli değildir.

Bu kursun tüm dersleri

← C# Academy Sayfasına Dön