Web API kurallarını kullanma

Makale
11/30/2023

Ortak API belgeleri ayıklanabilir ve bir derleme içindeki birden çok eyleme, denetleyiciye veya tüm denetleyicilere uygulanabilir. Web API'leri kuralları, ile [ProducesResponseType]tek tek eylemlerin dekorasyonu için bir alternatiftir.

Bir kural şunları yapmanızı sağlar:

Belirli bir eylem türünden döndürülen en yaygın dönüş türlerini ve durum kodlarını tanımlayın.
Tanımlanan standarttan sapan eylemleri belirleyin.

Varsayılan kurallar içinden Microsoft.AspNetCore.Mvc.DefaultApiConventionskullanılabilir. Kurallar, BIR API proje şablonuna ValuesController.cs eklenen ile gösterilir:

using Microsoft.AspNetCore.Mvc;
using System.Collections.Generic;

namespace WebApp1.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class ValuesController : ControllerBase
    {
        // GET api/values
        [HttpGet]
        public ActionResult<IEnumerable<string>> Get()
        {
            return new string[] { "value1", "value2" };
        }

        // GET api/values/5
        [HttpGet("{id}")]
        public ActionResult<string> Get(int id)
        {
            return "value";
        }

        // POST api/values
        [HttpPost]
        public void Post([FromBody] string value)
        {
        }

        // PUT api/values/5
        [HttpPut("{id}")]
        public void Put(int id, [FromBody] string value)
        {
        }

        // DELETE api/values/5
        [HttpDelete("{id}")]
        public void Delete(int id)
        {
        }
    }
}

Çalışmadaki ValuesController.cs desenleri izleyen eylemler ve varsayılan kurallar. Varsayılan kurallar gereksinimlerinizi karşılamıyorsa bkz . Web API'si kuralları oluşturma.

Çalışma zamanında kuralları Microsoft.AspNetCore.Mvc.ApiExplorer anlar. ApiExplorer, MVC'nin OpenAPI (Swagger olarak da bilinir) belge oluşturucularıyla iletişim kurma soyutlamasıdır. Uygulanan kuraldaki öznitelikler bir eylemle ilişkilendirilir ve eylemin OpenAPI belgelerine eklenir. API çözümleyicileri kuralları da anlar. Eyleminiz geleneksel değilse (örneğin, uygulanan kural tarafından belgelenmeyen bir durum kodu döndürür), bir uyarı durum kodunu belgelemenizi teşvik eder.

Örnek kodu görüntüleme veya indirme (indirme)

Web API kurallarını uygulama

Kurallar oluşturmaz; her eylem tam olarak bir kuralla ilişkilendirilebilir. Daha belirli kurallar, daha az belirli kurallardan önceliklidir. Aynı önceliğe sahip iki veya daha fazla kural bir eylem için geçerli olduğunda seçim belirlenemez. Bir eyleme en özelden en az belirliye kadar bir kural uygulamak için aşağıdaki seçenekler vardır:

Microsoft.AspNetCore.Mvc.ApiConventionMethodAttribute — Tek tek eylemler için geçerlidir ve geçerli olan kural türünü ve kural yöntemini belirtir.

Aşağıdaki örnekte, eyleme varsayılan kural türünün Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put kural yöntemi uygulanır Update :

// PUT api/contactsconvention/{guid}
[HttpPut("{id}")]
[ApiConventionMethod(typeof(DefaultApiConventions), 
                     nameof(DefaultApiConventions.Put))]
public IActionResult Update(string id, Contact contact)
{
    var contactToUpdate = _contacts.Get(id);

    if (contactToUpdate == null)
    {
        return NotFound();
    }

    _contacts.Update(contact);

    return NoContent();
}

kural Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put yöntemi eyleme aşağıdaki öznitelikleri uygular:

[ProducesDefaultResponseType]
[ProducesResponseType(StatusCodes.Status204NoContent)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]

hakkında [ProducesDefaultResponseType]daha fazla bilgi için bkz . Varsayılan Yanıt.

Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute bir denetleyiciye uygulandı — Belirtilen kural türünü denetleyicideki tüm eylemlere uygular. Bir kural yöntemi, kural yönteminin uygulandığı eylemleri belirleyen ipuçlarıyla işaretlenir. İpuçları hakkında daha fazla bilgi için bkz . Web API'si kuralları oluşturma).

Aşağıdaki örnekte, varsayılan kural kümesi ContactsConventionController içindeki tüm eylemlere uygulanır:
```
[ApiController]
[ApiConventionType(typeof(DefaultApiConventions))]
[Route("api/[controller]")]
public class ContactsConventionController : ControllerBase
{
```
Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute bir derlemeye uygulandı — Belirtilen kural türünü geçerli derlemedeki tüm denetleyicilere uygular. Öneri olarak, dosyaya Startup.cs derleme düzeyi öznitelikleri uygulayın.

Aşağıdaki örnekte, varsayılan kural kümesi derlemedeki tüm denetleyicilere uygulanır:
```
[assembly: ApiConventionType(typeof(DefaultApiConventions))]
namespace ApiConventions
{
    public class Startup
    {
```

Web API'leri kuralları oluşturma

Varsayılan API kuralları gereksinimlerinizi karşılamıyorsa kendi kurallarınızı oluşturun. Kural:

Yöntemleri olan statik bir tür.
Eylemlerde yanıt türlerini ve adlandırma gereksinimlerini tanımlama özelliğine sahiptir.

Yanıt türleri

Bu yöntemlere veya [ProducesDefaultResponseType] öznitelikleriyle açıklama eklenir[ProducesResponseType]. Örnek:

public static class MyAppConventions
{
    [ProducesResponseType(StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status404NotFound)]
    public static void Find(int id)
    {
    }
}

Daha belirli meta veri öznitelikleri yoksa, bu kuralın bir derlemeye uygulanması aşağıdakileri zorunlu kılır:

kural yöntemi, adlı Findherhangi bir eylem için geçerlidir.
Eylemin üzerinde Find adlı id bir parametre var.

Adlandırma gereksinimleri

[ApiConventionNameMatch] ve [ApiConventionTypeMatch] öznitelikleri, uygulandıkları eylemleri belirleyen kural yöntemine uygulanabilir. Örnek:

[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
[ApiConventionNameMatch(ApiConventionNameMatchBehavior.Prefix)]
public static void Find(
    [ApiConventionNameMatch(ApiConventionNameMatchBehavior.Suffix)]
    int id)
{ }

Yukarıdaki örnekte:

Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Prefix yöntemine uygulanan seçenek, kuralın "Bul" ön eki eklenmiş herhangi bir eylemle eşleşdiğini gösterir. Eşleşen eylemlere örnek olarak Find, FindPetve FindByIdverilebilir.
Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Suffix parametresine uygulanan, kuralın sonek tanımlayıcısıyla biten bir parametreyle yöntemleri eşleştirdiğini gösterir. Örnek olarak veya petIdgibi id parametreler verilebilir. ApiConventionTypeMatch , parametre türünü kısıtlamak için türlere benzer şekilde uygulanabilir. Bağımsız params[] değişken, açıkça eşleşmesi gerekmeyen kalan parametreleri gösterir.

Share via