Aracılığıyla paylaş

Web API kurallarını kullanma

Ortak API belgeleri ayıklanabilir ve bir derleme içindeki birden çok eyleme, denetleyiciye veya tüm denetleyicilere uygulanabilir. Web API kuralları, [ProducesResponseType] içeren tek tek eylemlerin dekorasyonuna 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 ValuesController.cs proje şablonuna 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)
        {
        }
    }
}

ValuesController.cs desenlerini izleyen eylemler varsayılan kurallarla uyumlu çalışır. Varsayılan kurallar gereksinimlerinizi karşılamıyorsa bkz. Web API'si kuralları oluşturma.

Microsoft.AspNetCore.Mvc.ApiExplorer çalışma zamanında konvansiyonları 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:

  1. 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.

  2. 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
{

  3. 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 kuralları oluşturma

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

Yanıt türleri

Bu yöntemler [ProducesResponseType] veya [ProducesDefaultResponseType] öznitelikleriyle açıklama eklenmiştir. Örneğin:

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 id adlı Find bir parametre var.

Adlandırma gereksinimleri

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

[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. Örnekler, id veya petId gibi parametreleri içerir. ApiConventionTypeMatch , parametre türünü kısıtlamak için türlere benzer şekilde uygulanabilir. params[] argümanı, eşleştirilmesine gerek olmayan kalan parametreleri belirtir.

Ek kaynaklar

  • Last updated on