ASP.NET Core uygulamasına OpenAPI meta verilerini ekleme

Bu makalede, ASP.NET Core uygulamasında OpenAPI meta verilerinin nasıl ekleneceği açıklanmaktadır.

Uç noktalar için OpenAPI meta verilerini ekleme

ASP.NET web uygulamasının uç noktalarından meta verileri toplar ve bunu kullanarak bir OpenAPI belgesi oluşturur.

Denetleyici tabanlı uygulamalarda meta veriler , [EndpointDescription]gibi [HttpPost]özniteliklerden ve [Produces] denetleyici özniteliğine[ApiController] sahip olduğunda toplanır.

En düşük API'lerde meta veriler özniteliklerden toplanabilir, ancak yol işleyicilerinden döndürme TypedResults gibi uzantı yöntemleri ve diğer stratejiler kullanılarak da ayarlanabilir.

Aşağıdaki tabloda, toplanan meta veriler ve ayarlama stratejilerine genel bir bakış sağlanmaktadır.

Meta veri	Öznitelik	Uzantı yöntemi	Diğer stratejiler
Özet	[EndpointSummary]	WithSummary
açıklama	[EndpointDescription]	WithDescription
etiketler	[Tags]	WithTags
operationId (İşlem Kimliği)	[EndpointName]	WithName
parametreler	[FromQuery], [FromRoute], [FromHeader], [FromForm]
parametre açıklaması	[Description]
requestBody	[FromBody]	Accepts
Yanıt	[Produces]	Produces, ProducesProblem	TypedResults
Uç noktaları hariç tutma	[ExcludeFromDescription], [ApiExplorerSettings]	ExcludeFromDescription

ASP.NET Core, XML belge açıklamalarından meta verileri toplamaz.

Aşağıdaki bölümlerde, oluşturulan OpenAPI belgesini özelleştirmek için bir uygulamaya meta verilerin nasıl ekileceği gösterilmektedir.

Özet ve açıklama

Uç nokta özeti ve açıklaması, [EndpointSummary] ve [EndpointDescription] öznitelikleri kullanılarak veya minimal API'lerde WithSummary ve WithDescription uzantı yöntemleri kullanılarak ayarlanabilir.

Minimum API'ler

Aşağıdaki örnekte özetleri ve açıklamaları ayarlamaya yönelik farklı stratejiler gösterilmektedir.

Özniteliklerin app.MapGet yöntemine değil, temsilci yöntemine yerleştirildiğini unutmayın.

app.MapGet("/extension-methods", () => "Hello world!")
    .WithSummary("This is a summary.")
    .WithDescription("This is a description.");

app.MapGet("/attributes",
    [EndpointSummary("This is a summary.")]
    [EndpointDescription("This is a description.")]
    () => "Hello world!");

Denetleyiciler

Aşağıdaki örnekte özetlerin ve açıklamaların nasıl ayarlanacağı gösterilmektedir.

[EndpointSummary("This is a summary.")]
[EndpointDescription("This is a description.")]
[HttpGet("attributes")]
public IResult Attributes()
{
    return Results.Ok("Hello world!");
}

etiketler

OpenAPI, her uç noktada etiketleri kategorilere ayırma biçimi olarak belirtmeyi destekler.

Minimum API'ler

Minimum API'lerde etiketler ya `[Tags]` özniteliğiyle ya da `WithTags` uzantı yöntemiyle ayarlanabilir.

Aşağıdaki örnekte etiketleri ayarlamaya yönelik farklı stratejiler gösterilmektedir.

app.MapGet("/extension-methods", () => "Hello world!")
    .WithTags("todos", "projects");

app.MapGet("/attributes",
    [Tags("todos", "projects")]
    () => "Hello world!");

Denetleyiciler

Denetleyici tabanlı uygulamalarda, denetleyici adı her uç noktasına otomatik olarak etiket olarak eklenir, ancak özniteliği kullanılarak [Tags] bu geçersiz kılınabilir.

Aşağıdaki örnekte etiketlerin nasıl ayarlanacağı gösterilmektedir.

[Tags(["todos", "projects"])]
[HttpGet("attributes")]
public IResult Attributes()
{
    return Results.Ok("Hello world!");
}

operationId (İşlem Kimliği)

OpenAPI, her uç noktada işlem için benzersiz bir tanımlayıcı veya ad olarak bir operationId'yi destekler.

Minimum API'ler

Minimum API'lerde ya [EndpointName] özniteliğini ya da WithName uzantı yöntemini kullanarak operationId ayarlanabilir.

Aşağıdaki örnekte operationId değerini ayarlamaya yönelik farklı stratejiler gösterilmektedir.

app.MapGet("/extension-methods", () => "Hello world!")
    .WithName("FromExtensionMethods");

app.MapGet("/attributes",
    [EndpointName("FromAttributes")]
    () => "Hello world!");

Denetleyiciler

Denetleyici tabanlı uygulamalarda operationId özniteliği kullanılarak [EndpointName] ayarlanabilir.

Aşağıdaki örnekte operationId değerinin nasıl ayarlanacağı gösterilmektedir.

[EndpointName("FromAttributes")]
[HttpGet("attributes")]
public IResult Attributes()
{
    return Results.Ok("Hello world!");
}

parametreler

OpenAPI, bir API tarafından kullanılan yol, sorgu dizesi, üst bilgi ve cookie parametrelere açıklama eklemeyi destekler.

Çerçeve, yol işleyicisinin imzasını temel alarak istek parametrelerinin türlerini otomatik olarak çıkarsar.

[Description] özniteliği, bir parametre için açıklama sağlamak için kullanılabilir.

Minimum API'ler

[Description] özniteliği bir MVC uygulamasında çalışır ancak bu, şu anda Minimal API uygulamasında çalışmaz. Daha fazla bilgi için bkz. Description parametresi ProducesResponseTypeAttribute minimal API uygulamasında çalışmıyor (dotnet/aspnetcore #60518)

Denetleyiciler

Aşağıdaki örnekte bir parametre için açıklamanın nasıl ayarlanacağı gösterilmektedir.

[HttpGet("attributes")]
public IResult Attributes([Description("This is a description.")] string name)
{
    return Results.Ok("Hello world!");
}

İstek gövdesini tanımla

requestBody OpenAPI'deki alan, desteklenen içerik türleri ve gövde içeriğinin şeması dahil olmak üzere bir API istemcisinin sunucuya gönderebileceği bir isteğin gövdesini açıklar.

Uç nokta işleyici yöntemi, istek gövdesinden bağlanan parametreleri kabul ettiğinde, ASP.NET Core, OpenAPI belgesindeki işlem için karşılık gelen bir requestBody oluşturur. İstek gövdesi için meta veriler, öznitelikler veya uzantı yöntemleri kullanılarak da belirtilebilir. Ek meta veriler bir belge transformatörü veya işlem transformatörü ile ayarlanabilir.

Uç nokta, istek gövdesine bağlı parametre tanımlamaz ancak bunun yerine doğrudan istek gövdesini HttpContext kullanırsa ASP.NET Core, istek gövdesi meta verilerini belirtmek için mekanizmalar sağlar. Bu, istek gövdesini akış olarak işleyen uç noktalar için yaygın bir senaryodur.

Bazı istek gövdesi meta verileri, yol işleyici yönteminin FromBody veya FromForm parametrelerinden belirlenebilir.

İstek gövdesi için bir açıklama, bir parametredeki [Description] özniteliği kullanılarak FromBody veya FromForm ile ayarlanabilir.

FromBody Parametresi null olmamalıysa ve EmptyBodyBehaviorAllow özelliğinde FromBody olarak ayarlanmamışsa, istek gövdesi gereklidir ve required'nin requestBody alanı oluşturulan OpenAPI belgesinde true olarak ayarlanır. Form gövdeleri her zaman gereklidir ve required, true olarak ayarlanmıştır.

" doküman çeviricisi veya işlem çeviricisi kullanarak, example, examples veya encoding alanlarını ayarlayın ya da üretilen OpenAPI belgesinde istek gövdesi için özel uzantılar ekleyin."

İstek gövdesi meta verilerini ayarlamaya yönelik diğer mekanizmalar, geliştirilmekte olan uygulamanın türüne bağlıdır ve aşağıdaki bölümlerde açıklanmıştır.

Minimum API'ler

Oluşturulan OpenAPI belgesindeki istek gövdesinin içerik türleri, istek gövdesine bağlı olan veya uzantı yöntemiyle belirtilen parametrenin türünden Accepts belirlenir. Varsayılan olarak, bir FromBody parametrenin içerik türü ve application/json parametrelerin içerik türü FromForm veya multipart/form-dataolurapplication/x-www-form-urlencoded.

Bu varsayılan içerik türleri için destek En Düşük API'lerde yerleşiktir ve diğer içerik türleri özel bağlama kullanılarak işlenebilir. Minimal API'lerin belgelerindeki Özel bağlama bölümüne daha fazla bilgi için bakın.

İstek gövdesi için farklı bir içerik türü belirtmenin çeşitli yolları vardır. Eğer FromBody parametresinin türü IEndpointParameterMetadataProvider'i uygularsa, ASP.NET Core bu arabirimi istek gövdesindeki içerik türlerini belirlemek için kullanır. Çerçeve, bu arabirimin PopulateMetadata yöntemini kullanarak istek gövdesinin gövde içeriğinin içerik tür(leri)ni ve türünü ayarlar. Örneğin, Todo veya application/xml içerik türünü kabul eden bir text/xml sınıfı, bu bilgiyi çerçeveye sağlamak için IEndpointParameterMetadataProvider kullanabilir.

public class Todo : IEndpointParameterMetadataProvider
{
    public static void PopulateMetadata(ParameterInfo parameter, EndpointBuilder builder)
    {
        builder.Metadata.Add(new AcceptsMetadata(["application/xml", "text/xml"], typeof(Todo)));
    }
}

Accepts Uzantı yöntemi, istek gövdesinin içerik türünü belirtmek için de kullanılabilir. Aşağıdaki örnekte, uç nokta istek gövdesinde beklenen içerik türüne Todosahip bir nesne kabul ederapplication/xml.

app.MapPut("/todos/{id}", (int id, Todo todo) => ...)
    .Accepts<Todo>("application/xml");

application/xml yerleşik bir içerik türü olmadığından, Todo sınıfı, istek gövdesi için özel bir bağlama sağlamak amacıyla IBindableFromHttpContext<TSelf> arabirimini uygulamalıdır. Örneğin:

public class Todo : IBindableFromHttpContext<Todo>
{
    public static async ValueTask<Todo?> BindAsync(HttpContext context, ParameterInfo parameter)
    {
        var xmlDoc = await XDocument.LoadAsync(context.Request.Body, LoadOptions.None, context.RequestAborted);
        var serializer = new XmlSerializer(typeof(Todo));
        return (Todo?)serializer.Deserialize(xmlDoc.CreateReader());
    }
}

Uç nokta, istek gövdesine bağlı parametre tanımlamıyorsa, uç noktanın Accepts kabul ettiğini içerik türünü belirtmek için uzantı yöntemini kullanın.

AspNetCore.Http.OpenApiRouteHandlerBuilderExtensions.Accepts%2A'yı< birden çok kez belirtirseniz>, yalnızca son meta veriler kullanılır; bunlar birleştirilmemiştir.

Denetleyiciler

Denetleyici tabanlı uygulamalarda, oluşturulan OpenAPI belgesindeki istek gövdesinin içerik türleri, istek gövdesine bağlı parametrenin türünden, InputFormatter uygulamada yapılandırılan türlerden veya yol işleyici yöntemindeki bir [Consumes] öznitelik tarafından belirlenir.

ASP.NET Core, bir InputFormatter kullanarak FromBody istek gövdesini seri durumdan çıkarır. InputFormatters, MvcOptions içinde uygulamanın hizmet koleksiyonu için uzantı yöntemine geçirilen AddControllers yapılandırılır. Her giriş biçimlendirici, SupportedMediaTypes özelliği ile işleyebileceği içerik türlerini ve CanReadType yöntemi ile işleyebileceği gövde içeriğinin türlerini bildirir.

ASP.NET Core MVC, JSON ve XML için yerleşik giriş biçimlendiricileri içerir, ancak varsayılan olarak yalnızca JSON giriş biçimlendiricisi etkindir. Yerleşik JSON giriş biçimlendiricisi application/json, text/jsonve application/*+json içerik türlerini, yerleşik XML giriş biçimlendiricisi ise , application/xmlve text/xml içerik türlerini desteklerapplication/*+xml.

Varsayılan olarak, bir FromBody istek gövdesinin içerik türü parametre türü için InputFormatter tarafından kabul edilen herhangi bir FromBody içerik türü olabilir. Parametreleri olan bir istek gövdesi için varsayılan içerik türleri FromForm veya multipart/form-data şeklindedir. Bu içerik türleri, application/x-www-form-urlencoded özniteliği yol işleyici yönteminde belirtilmediği takdirde, oluşturulan OpenAPI belgesine eklenir.

Yol işleyicisi tarafından kabul edilen içerik türleri, uç nokta üzerindeki bir filtre (eylem kapsamı) kullanılarak kısıtlanabilir. özniteliği, [Consumes] uç noktaya bir yol işleyicisinin kabul edeceği içerik türlerini kısıtlayan bir eylem kapsamı filtresi ekler. Bu durumda, oluşturulan OpenAPI belgesindeki requestBody yalnızca öznitelikte [Consumes] belirtilen içerik türlerini içerir.

[Consumes] Öznitelik, ilişkili giriş biçimlendiricisi olmayan bir içerik türü için destek ekleyemez ve oluşturulan OpenAPI belgesinde ilişkili giriş biçimlendiricisi olmayan içerik türleri yoktur.

JSON veya XML dışındaki içerik türleri için özel bir giriş biçimlendirici oluşturmanız gerekir. Daha fazla bilgi ve örnek için bkz . ASP.NET Core Web API'sindeki özel biçimlendiriciler.

Yol işleyicisinin FromBody veya FromForm parametresi yoksa, yol işleyicisi isteğin gövdesini Request.Body akışından doğrudan okuyabilir ve izin verilen içerik türlerini kısıtlamak için [Consumes] özniteliğini kullanabilir, ancak OpenAPI belgesinde bir requestBody oluşturulmaz.

Yanıt türlerini açıklama

OpenAPI, API'den döndürülen yanıtların açıklamasını sağlamayı destekler. ASP.NET Core, bir uç noktanın yanıt meta verilerini ayarlamak için çeşitli stratejiler sağlar. Ayarlanabilen yanıt meta verileri durum kodunu, yanıt gövdesinin türünü ve yanıtın içerik türlerini içerir. OpenAPI'deki yanıtlarda açıklama, üst bilgiler, bağlantılar ve örnekler gibi ek meta veriler bulunabilir. Bu ek meta veriler bir belge transformatörü veya işlem transformatörü ile ayarlanabilir.

Yanıt meta verilerini ayarlamaya yönelik belirli mekanizmalar, geliştirilmekte olan uygulamanın türüne bağlıdır.

Minimum API'ler

En Düşük API uygulamalarında ASP.NET Core, uç noktadaki uzantı yöntemleri, yol işleyicisindeki öznitelikler ve yol işleyicisinin dönüş türü tarafından eklenen yanıt meta verilerini ayıklayabilir.

• Uzantı Produces yöntemi, durum kodunu, yanıt gövdesinin türünü ve bir uç noktadan gelen yanıtın içerik türlerini belirtmek için uç noktada kullanılabilir.
• [ProducesResponseType] veya ProducesResponseTypeAttribute<T> özniteliği, yanıt gövdesinin türünü belirtmek için kullanılabilir.
• Yol işleyicisi, yanıt gövdesinin türünü ve içerik türlerini belirtmek için IEndpointMetadataProvider uygulayan bir tür döndürmek amacıyla kullanılabilir.
• ProducesProblem Uç nokta üzerindeki uzantı yöntemi, bir hata yanıtının durum kodunu ve içerik türlerini belirtmek için kullanılabilir.

Produces ve ProducesProblem uzantısı yöntemlerinin hem RouteHandlerBuilder hem de RouteGroupBuilder üzerinde desteklendiğini unutmayın. Bu, örneğin bir gruptaki tüm işlemler için ortak bir hata yanıtları kümesinin tanımlanmasını sağlar.

Önceki stratejilerden biri tarafından belirtilmediğinde, şu durum meydana gelir:

• Yanıt için durum kodu varsayılan olarak 200'dır.
• Yanıt gövdesi şeması, uç nokta yönteminin örtük veya açık dönüş türünden( örneğin, T içinden Task<TResult>) çıkarılabilir; aksi takdirde belirtilmemiş olarak kabul edilir.
• Belirtilen veya çıkarsanan yanıt gövdesi için içerik türü "application/json" şeklindedir.

En Düşük API'lerde uzantı Produces yöntemi ve [ProducesResponseType] özniteliği yalnızca uç nokta için yanıt meta verilerini ayarlar. Uç noktanın davranışını değiştirmez veya kısıtlamaz; bu da meta veriler tarafından belirtilenden farklı bir durum kodu veya yanıt gövdesi türü döndürebilir ve içerik türü, özniteliklerde veya uzantı yöntemlerinde belirtilen içerik türünden bağımsız olarak yol işleyici yönteminin dönüş türü tarafından belirlenir.

Produces Uzantı yöntemi, varsayılan durum kodu 200 ve varsayılan içerik türü olan bir uç noktanın yanıt türünü application/jsonbelirtebilir. Aşağıdaki örnekte bu gösterilmektedir:

app.MapGet("/todos", async (TodoDb db) => await db.Todos.ToListAsync())
    .Produces<IList<Todo>>();

bir [ProducesResponseType] uç noktaya yanıt meta verileri eklemek için kullanılabilir. Özniteliğin, aşağıdaki örnekte gösterildiği gibi yolu oluşturmak için yöntem çağırma yöntemine değil yol işleyici yöntemine uygulandığını unutmayın:

app.MapGet("/todos",
    [ProducesResponseType<List<Todo>>(200)]
    async (TodoDb db) => await db.Todos.ToListAsync());

Uç noktanın yol işleyicisinin uygulanmasında kullanılması TypedResults , uç nokta için yanıt türü meta verilerini otomatik olarak içerir. Örneğin, aşağıdaki kod, 200 durum koduyla ve application/json içerik türünde bir yanıtı uç noktaya otomatik olarak açıklama olarak ekler.

app.MapGet("/todos", async (TodoDb db) =>
{
    var todos = await db.Todos.ToListAsync();
    return TypedResults.Ok(todos);
});

Yalnızca OpenAPI belgesinde bir IEndpointMetadataProvider girdisi oluşturan dönüş türleri responses uygular. Aşağıda, TypedResults girdi oluşturan bazı yardımcı yöntemlerin responses kısmi listesi yer alıyor.

TypedResults yardımcı yöntemi	Durum kodu
Ok()	200
Oluşturuldu()	201
RotaÜzerindeOluşturuldu()	201
Kabul edildi	202
AcceptedAtRoute()	202
İçerik Yok	204
BadRequest()	400
ValidationProblem()	400
Bulunamadı()	404
Çatışma()	409
UnprocessableEntity() // İşlenemeyen Varlık	422

NoContent hariç diğer tüm bu yöntemlerin, yanıt gövdesinin türünü belirten genel bir aşırı yüklemesi vardır.

Uç nokta meta verilerini ayarlamak ve yol işleyicisinden döndürmek için bir sınıf uygulanabilir.

Yanıtları ProblemDetails için ayarla

ProblemDetails yanıtı döndürebilecek uç noktaların yanıt türünü ayarlarken, uç nokta için uygun yanıt meta verilerini eklemek için aşağıdakiler kullanılabilir:

• ProducesProblem
• ProducesValidationProblem uzantı metodu.
• TypedResults (400-499) aralığında bir durum koduyla.

Minimal API uygulamasını ProblemDetails yanıtları döndürecek şekilde yapılandırma hakkında daha fazla bilgi için, Minimal API'lerde hataları yönetme bölümüne bakın.

Birden çok yanıt türü

Bir uç nokta farklı senaryolarda farklı yanıt türleri döndürebiliyorsa meta verileri aşağıdaki yollarla sağlayabilirsiniz:

• Produces Aşağıdaki örnekte gösterildiği gibi uzantı yöntemini birden çok kez çağırın:

  app.MapGet("/api/todoitems/{id}", async (int id, TodoDb db) =>
           await db.Todos.FindAsync(id) 
           is Todo todo
           ? Results.Ok(todo) 
           : Results.NotFound())
     .Produces<Todo>(StatusCodes.Status200OK)
     .Produces(StatusCodes.Status404NotFound);
  

• Aşağıdaki örnekte gösterildiği gibi, Results<TResult1,TResult2,TResult3,TResult4,TResult5,TResult6> imzada ve TypedResults işleyicinin gövdesinde kullanın.

  app.MapGet("/book/{id}", Results<Ok<Book>, NotFound> 
      (int id, List<Book> bookList) =>
      {
          return bookList.FirstOrDefault((i) => i.Id == id) is Book book
          ? TypedResults.Ok(book)
          : TypedResults.NotFound();
      });
  

  Birleşim Results<TResult1,TResult2,TResultN>türleri, bir yol işleyicisinin birden fazla IResult uygulayan somut tür döndürdüğünü bildirir. Bu somut türlerin herhangi biri IEndpointMetadataProvider uyguluyorsa, uç noktanın meta verilerine katkı sağlar.

  Birleşim türleri örtük dönüştürme operatörleri kullanır. Bu işleçler, derleyicinin genel bağımsız değişkenlerde belirtilen türleri birleşim türünün bir örneğine otomatik olarak dönüştürmesini sağlar. Bu özellik, bir yol işleyicisinin yalnızca bildirdiği sonuçları döndürdüğüne ilişkin derleme zamanı denetimi sağlama avantajına sahiptir. Genel bağımsız değişkenlerden biri olarak bildirilmemiş bir tür döndürmeye çalışmak, Results<TResult1,TResult2,TResultN> derleme hatası ile sonuçlanır.

Denetleyiciler

Denetleyici tabanlı uygulamalarda ASP.NET Core, eylem yöntemi imzası, öznitelikleri ve kurallarından yanıt meta verilerini ayıklayabilir.

• Bir eylem yönteminden gelen yanıtın durum kodunu, yanıt gövdesinin türünü ve içerik türlerini belirtmek için [ProducesResponseType] veya ProducesResponseTypeAttribute<T> özniteliğini kullanabilirsiniz.
• yanıt gövdesinin [Produces] türünü belirtmek için veya ProducesAttribute<T> özniteliğini kullanabilirsiniz.
• özniteliğini [ProducesDefaultResponseType] kullanarak "varsayılan" yanıt için yanıt gövdesi türünü belirtebilirsiniz.
• Hata yanıtının [ProducesErrorResponseType] yanıt gövdesi türünü belirtmek için özniteliğini kullanabilirsiniz. Ancak, bunun yalnızca 4XX durum koduna sahip bir [ProducesResponseType] öznitelik tarafından belirtilen durum kodunu ve içerik türlerini tamamladığını unutmayın.

Bir eylem yöntemine yalnızca bir veya [Produces]ProducesAttribute<T> öznitelik uygulanabilir, ancak tek bir eylem yöntemine farklı durum kodlarına sahip birden çok [ProducesResponseType] veya ProducesResponseTypeAttribute<T> öznitelik uygulanabilir.

Yukarıdaki özniteliklerin tümü tek tek eylem yöntemlerine veya denetleyicideki tüm eylem yöntemleri için geçerli olduğu denetleyici sınıfına uygulanabilir.

Bir öznitelik tarafından belirtilmediğinde:

• Yanıt için durum kodu varsayılan olarak 200'dır.
• 2xx yanıtların yanıt gövdesi şeması, eylem yönteminin dönüş türünden (örneğin T , içinde ActionResult<TValue>) çıkarılabilir, ancak aksi takdirde belirtilmemiş olarak kabul edilir.
• 4xx yanıtlarının yanıt gövdesi şemasının bir sorun detayları nesnesi olduğu çıkarım yapılır.
• 3xx ve 5xx yanıtlarının yanıt gövdesi şemasının belirtilmemiş olduğu kabul edilir.
• Yanıt gövdesinin içerik türü, eylem yönteminin dönüş türünden ve çıkış biçimlendiricileri kümesinden çıkarılabilir.

Varsayılan olarak, [ProducesResponseType] özniteliği ile belirtilen yanıt meta verilerinin eylem yönteminin gerçek davranışıyla tutarlı olduğundan emin olmak için derleme zamanı denetimleri yoktur ve bu da meta veriler tarafından belirtilenden farklı bir durum kodu veya yanıt gövdesi türü döndürebilir. Bu denetimleri etkinleştirmek için Web API çözümleyicilerini etkinleştirin.

Denetleyici tabanlı uygulamalarda ASP.NET, model doğrulaması başarısız olduğunda veya eylem yöntemi 4xx veya 5xx HTTP durum koduyla sonuç döndürdüğünde ProblemDetails yanıt türüyle yanıt verir. Doğrulama hataları genellikle 400 durum kodunu kullanır, bu nedenle aşağıdaki örnekte gösterildiği gibi bir eylemin hata yanıtını belirtmek üzere [ProducesResponseType] özniteliği kullanabilirsiniz:

[HttpPut("/todos/{id}")]
[ProducesResponseType<Todo>(StatusCodes.Status200OK, "application/json")]
[ProducesResponseType<Todo>(StatusCodes.Status201Created, "application/json")]
[ProducesResponseType<ProblemDetails>(StatusCodes.Status400BadRequest, "application/problem+json")]
public async Task<ActionResult<Todo>> CreateOrReplaceTodo(string id, Todo todo)

Bu örnekte, yanıt gövdesinin içerik türü de dahil olmak üzere bir eylem yöntemi için birden çok yanıt türünün nasıl tanımlanacağı da gösterilmektedir.

Uç noktaları oluşturulan belgenin dışında tutma

Varsayılan olarak, bir uygulamada tanımlanan tüm uç noktalar oluşturulan OpenAPI dosyasında belgelenir, ancak uç noktalar öznitelikler veya uzantı yöntemleri kullanılarak belgenin dışında tutulabilir.

Dışlanması gereken bir uç nokta belirtme mekanizması, geliştirilmekte olan uygulamanın türüne bağlıdır.

Minimum API'ler

Minimum API'ler, belirli bir uç noktayı OpenAPI belgesinden dışlamak için iki stratejiyi destekler:

• ExcludeFromDescription uzantı yöntemi
• [ExcludeFromDescription] özniteliği

Aşağıdaki örnek, belirli bir uç noktayı oluşturulan OpenAPI belgesinden dışlamak için farklı stratejileri gösterir.

app.MapGet("/extension-method", () => "Hello world!")
    .ExcludeFromDescription();

app.MapGet("/attributes",
    [ExcludeFromDescription]
    () => "Hello world!");

Denetleyiciler

Denetleyici tabanlı uygulamalarda özniteliği, [ApiExplorerSettings] bir uç noktayı veya bir denetleyici sınıfındaki tüm uç noktaları OpenAPI belgesinin dışında tutmak için kullanılabilir.

Aşağıdaki örnekte, bir uç noktanın oluşturulan OpenAPI belgesinden nasıl dışlandığı gösterilmektedir:

[HttpGet("/private")]
[ApiExplorerSettings(IgnoreApi = true)]
public IActionResult PrivateEndpoint() {
    return Ok("This is a private endpoint");
}

Veri türleri için OpenAPI meta verilerini dahil et

İstek veya yanıt gövdelerinde kullanılan C# sınıfları veya kayıtları, oluşturulan OpenAPI belgesinde şema olarak temsil edilir. Varsayılan olarak, şemada yalnızca genel özellikler temsil edilir, ancak JsonSerializerOptions alanlar için şema özellikleri de oluşturulur.

PropertyNamingPolicy deve sırtı stili olarak ayarlandığında (ASP.NET web uygulamalarında varsayılan değerdir), şemadaki özellik adları, sınıf veya kayıt özellik adının deve sırtı stilinde biçimidir. , [JsonPropertyName] şemadaki özelliğin adını belirtmek için tek bir özellikte kullanılabilir.

tür ve biçim

JSON Şema kitaplığı, standart C# türlerini OpenAPI type ile ve format aşağıdaki gibi eşler:

C# Türü	OpenAPI type	OpenAPI format
Int	tamsayı	int32
uzun	tamsayı	int64
kısa	tamsayı	int16
bayt	tamsayı	uint8
yüzer	Numara	yüzer
çift	Numara	çift
ondalık	Numara	çift
boolean	Boolean
Dize	Dize
Char	Dize	Char
bayt[]	Dize	bayt
TarihSaatOfset	Dize	tarih-saat
Sadece Tarih	Dize	tarih
TimeOnly	Dize	zaman
Urı	Dize	URI
GUID	Dize	UUID (evrensel benzersiz tanımlayıcı)
nesne	Çıkarıldı
dinamik	Çıkarıldı

Nesne ve dinamik türlerin OpenAPI'de tanımlı türü olmadığını unutmayın çünkü bunlar int veya dize gibi ilkel türler de dahil olmak üzere herhangi bir türde veri içerebilir.

type veformat, şema transformatörü ile de ayarlanabilir. Örneğin, ondalık türlerinin format yerine decimalolmasını double isteyebilirsiniz.

Meta veri eklemek için öznitelikleri kullanma

ASP.NET, oluşturulan şemanın ilgili özelliklerinde meta verileri ayarlamak için sınıf veya kayıt özelliklerindeki özniteliklerden meta verileri kullanır.

Aşağıdaki tabloda, System.ComponentModel ad alanından sağlanan ve oluşturulan şema için meta veriler içeren öznitelikler özetlenmiştir.

Öznitelik	Açıklama
[Description]	Şemadaki description bir özelliğin değerini ayarlar.
[Required]	Bir özelliği şemada olarak required işaretler.
[DefaultValue]	Şemadaki default bir özelliğin değerini ayarlar.
[Range]	Bir tamsayının veya sayının minimum ve maximum değerini ayarlar.
[MinLength]	Bir dizenin minLength'sını veya bir dizinin minItems'ini ayarlar.
[MaxLength]	Bir dizenin maxLength'sını veya bir dizinin maxItems'ini ayarlar.
[RegularExpression]	Karakter dizisinin pattern değerini ayarlar.

Denetleyici tabanlı uygulamalarda, bu özniteliklerin gelen verilerin kısıtlamaları karşıladığını doğrulamak için işleme filtreler eklediğini unutmayın. En Düşük API'lerde, bu öznitelikler oluşturulan şemadaki meta verileri ayarlar, ancak doğrulamanın bir uç nokta filtresi, yol işleyicisinin mantığı veya üçüncü taraf paket aracılığıyla açıkça gerçekleştirilmesi gerekir.

Öznitelikler, kayıt tanımının parametre listesindeki parametrelere de yerleştirilebilir, ancak değiştiriciyi property içermelidir. Örneğin:

public record Todo(
    [property: Required]
    [property: Description("The unique identifier for the todo")]
    int Id,
    [property: Description("The title of the todo")]
    [property: MaxLength(120)]
    string Title,
    [property: Description("Whether the todo has been completed")]
    bool Completed
) {}

Oluşturulan şemalar için diğer meta veri kaynakları

gerekli

Bir sınıfta, yapıda veya kayıtta, özniteliğine veya gerekli değiştiriciye [Required] sahip özellikler her zaman ilgili şemadadır.required

Sınıf, yapı veya kayıt için oluşturuculara (örtük ve açık) göre diğer özellikler de gerekli olabilir.

• Tek bir ortak oluşturucuya sahip bir sınıf veya kayıt sınıfı için, oluşturucuya parametre olarak aynı tür ve isme sahip (büyük/küçük harf eşleşmelerine duyarsız) herhangi bir özellik, ilgili şemada gereklidir.
• Birden çok ortak oluşturucuya sahip bir sınıf veya kayıt sınıfı için başka bir özellik gerekmez.
• Bir yapı veya kayıt yapısı için, C# her zaman bir yapı için örtük parametresiz oluşturucu tanımladığından başka hiçbir özellik gerekmez.

sabit listesi

C#'daki enum türleri tamsayı tabanlıdır, ancak JSON'da bir [JsonConverter] ve bir JsonStringEnumConverter olarak dizeler şeklinde gösterilebilir. Bir sabit listesi türü JSON'da bir dize olarak temsil edildiğinde, oluşturulan şemanın sabit listesi dize değerlerine sahip bir enum özelliği olur.

JSON'da bir enum'u dize olarak göstermek için bir JsonStringEnumConverter'nın nasıl kullanılacağını aşağıdaki örnek göstermektedir:

[JsonConverter(typeof(JsonStringEnumConverter<DayOfTheWeekAsString>))]
public enum DayOfTheWeekAsString
{
    Sunday,
    Monday,
    Tuesday,
    Wednesday,
    Thursday,
    Friday,
    Saturday
}

Bir sabit listesi türünün, sabit listesinin bit alanı olarak ele alınabileceğini belirten [Flags] özniteliğine sahip olması özel bir durumdur; yani bir dizi bayrak. [JsonConverterAttribute] içeren bayraklar sabit listesi, oluşturulan şemada type: string özelliği olmayan enum olarak tanımlanır çünkü değer sabit listesi değerlerinin herhangi bir bileşimi olabilir. Örneğin, aşağıdaki enumerasyon:

[Flags, JsonConverter(typeof(JsonStringEnumConverter<PizzaToppings>))]
public enum PizzaToppings { Pepperoni = 1, Sausage = 2, Mushrooms = 4, Anchovies = 8 }

veya "Pepperoni, Sausage"gibi "Sausage, Mushrooms, Anchovies" değerlere sahip olabilir.

[JsonConverter] içermeyen bir sabit listesi türü, oluşturulan şemada type: integer olarak tanımlanır.

Not:[AllowedValues] özniteliği bir özelliğin enum değerlerini ayarlamaz.

null olabilir

Null atanabilir değer veya referans türü olarak tanımlanan özellikler oluşturulan şemada nullable: true olarak görünür. Bu, null atanabilir bir özellik için System.Text.Json'i geçerli bir değer olarak kabul eden null seri durumdan çıkarıcının varsayılan davranışıyla tutarlıdır.

ek özellikler

Şemalar varsayılan olarak bir additionalProperties onayı olmadan oluşturulur ve bu, varsayılan olarak true anlamına gelir. Bu, bir JSON nesnesindeki ek özellikleri sessizce görmezden gelen System.Text.Json çözücüsünün varsayılan davranışıyla tutarlıdır.

Bir şemanın ek özellikleri yalnızca belirli bir türde değerlere sahip olmalıdır, özelliğini veya sınıfını olarak Dictionary<string, type>tanımlayın. Sözlüğün anahtar türü olmalıdır string. Bir additionalProperties şema oluşturarak "tür" için gerekli değer tipleri olarak şemayı belirler.

Polimorfik türler

Çok biçimli bir türün ayırıcı alanını ve alt türlerini belirtmek için üst sınıftaki [JsonPolymorphic] ve [JsonDerivedType] özniteliklerini kullanın.

[JsonDerivedType], her alt sınıf için ayrımcı alanını şemaya ekler ve alt sınıf için belirli ayrımcı değeri belirten bir enum ekler. Bu öznitelik, ayrıştırıcı değerini ayarlamak için türetilmiş her sınıfın oluşturucusunu da değiştirir.

Özniteliği olan soyut bir [JsonPolymorphic] sınıfın şemada bir discriminator alanı vardır, ancak bir [JsonPolymorphic] özniteliği olan somut sınıfın şemada discriminator alanı yoktur. OpenAPI, ayrımcı özelliğinin şemada gerekli bir özellik olmasını gerektirir, ancak ayırıcı özelliği somut temel sınıfta tanımlanmadığından şema bir discriminator alan içeremez.

Şema dönüştürücü ile meta veri ekleme

Şema transformatörü, varsayılan meta verileri geçersiz kılmak veya oluşturulan şemaya değerler gibi example ek meta veriler eklemek için kullanılabilir. Daha fazla bilgi için bkz . Şema dönüştürücülerini kullanma.

Ek kaynaklar

• Oluşturulan OpenAPI belgelerini kullanma
• OpenAPI belirtimi