Compartir a través de

Uso de convenciones de API web

La documentación de API común se puede extraer y aplicar a varias acciones, controladores o todos los controladores de un ensamblado. Las convenciones de API web son un sustituto de la decoración de acciones individuales con [ProducesResponseType].

Una convención le permite:

  • Defina los tipos de valor devueltos y los códigos de estado más comunes devueltos a partir de un tipo específico de acción.
  • Identifique las acciones que se desvían del estándar definido.

Las convenciones predeterminadas están disponibles en Microsoft.AspNetCore.Mvc.DefaultApiConventions. Las convenciones se muestran con el ValuesController.cs agregado a una plantilla de proyecto de API :

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)
        {
        }
    }
}

Acciones que siguen los patrones en el ValuesController.cs funcionan con las convenciones predeterminadas. Si las convenciones predeterminadas no satisfacen sus necesidades, consulte Creación de convenciones de API web.

En tiempo de ejecución, Microsoft.AspNetCore.Mvc.ApiExplorer comprende las convenciones. ApiExplorer es la abstracción de MVC para comunicarse con los generadores de documentos de OpenAPI (también conocido como Swagger). Los atributos de la convención aplicada están asociados a una acción y se incluyen en la documentación de OpenAPI de la acción. Los analizadores de API también comprenden las convenciones. Si la acción no es convencional (por ejemplo, devuelve un código de estado que no está documentado por la convención aplicada), una advertencia le anima a documentar el código de estado.

Consulta o descarga el código de ejemplo (cómo descargarlo)

Aplicación de convenciones de API web

Las convenciones no se componen; cada acción puede estar asociada exactamente a una convención. Las convenciones más específicas tienen prioridad sobre las convenciones menos específicas. La selección no es determinista cuando dos o más convenciones de la misma prioridad se aplican a una acción. Existen las siguientes opciones para aplicar una convención a una acción, desde la más específica hasta la menos específica:

  1. Microsoft.AspNetCore.Mvc.ApiConventionMethodAttribute : se aplica a acciones individuales y especifica el tipo de convención y el método de convención que se aplica.

    En el siguiente ejemplo, el método de convención predeterminado de tipo Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put se aplica a la acción 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();
}

    El Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put método de convención aplica los atributos siguientes a la acción:

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

    Para obtener más información sobre [ProducesDefaultResponseType], vea Respuesta predeterminada.

  2. Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute aplicado a un controlador: aplica el tipo de convención especificado a todas las acciones del controlador. Un método de convención se marca con sugerencias que determinan las acciones a las que se aplica el método de convención. Para más información sobre las sugerencias, consulte Creación de convenciones de API web).

    En el ejemplo siguiente, el conjunto predeterminado de convenciones se aplica a todas las acciones de ContactsConventionController:

    [ApiController]
[ApiConventionType(typeof(DefaultApiConventions))]
[Route("api/[controller]")]
public class ContactsConventionController : ControllerBase
{

  3. Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute aplicado a un ensamblado: aplica el tipo de convención especificado a todos los controladores del ensamblado actual. Como recomendación, aplique atributos de nivel de ensamblado en el Startup.cs archivo.

    En el ejemplo siguiente, el conjunto predeterminado de convenciones se aplica a todos los controladores del ensamblado:

    [assembly: ApiConventionType(typeof(DefaultApiConventions))]
namespace ApiConventions
{
    public class Startup
    {

Creación de convenciones de API web

Si las convenciones de API predeterminadas no satisfacen sus necesidades, cree sus propias convenciones. Una convención es:

Tipos de respuesta

Estos métodos se anotan con atributos [ProducesResponseType] o [ProducesDefaultResponseType]. Por ejemplo:

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

Si faltan atributos de metadatos más específicos, la aplicación de esta convención a un ensamblado exige que:

  • El método de convención se aplica a cualquier acción denominada Find.
  • Un parámetro denominado id está presente en la Find acción.

Requisitos de nomenclatura

Los [ApiConventionNameMatch] atributos y [ApiConventionTypeMatch] se pueden aplicar al método de convención que determina las acciones a las que se aplican. Por ejemplo:

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

En el ejemplo anterior:

  • La Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Prefix opción aplicada al método indica que la convención coincide con cualquier acción con el prefijo "Find". Algunos ejemplos de acciones coincidentes son Find, FindPety FindById.
  • El Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Suffix aplicado al parámetro indica que la convención coincide con métodos con exactamente un parámetro que termina con el sufijo identificador. Algunos ejemplos incluyen parámetros como id o petId. ApiConventionTypeMatch se puede aplicar de forma similar a los tipos para restringir el tipo de parámetro. Un params[] argumento indica los parámetros restantes que no necesitan coincidir explícitamente.

Recursos adicionales

  • Last updated on