Uso de convenciones de API web

  • Artículo

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 para complementar acciones individuales con [ProducesResponseType].

Una convención permite lo siguiente:

  • Definir los tipos de valor devuelto más comunes y los códigos de estado devueltos a partir de un tipo específico de acción.
  • Identificar las acciones que no siguen el 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 del trabajo ValuesController.cs 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 entiende las convenciones. ApiExplorer es la abstracción de MVC para comunicarse con los generadores de documento de OpenAPI, conocido también como Swagger. Los atributos de la convención aplicada se asocian 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 no documentado en la convención aplicada), recibirá una advertencia en la que se le animará a documentar el código de estado.

Vea o descargue el código de ejemplo (cómo descargarlo)

Aplicación de convenciones de API web

Las convenciones no se crean, y es posible que cada acción esté asociada a una única convención. Las convenciones más específicas tienen prioridad sobre las menos específicas. La selección es no determinista cuando se aplican dos o más convenciones de la misma prioridad a una acción. Las siguientes opciones existen para aplicar una convención a una acción, de la más específica a la menos específica:

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

    En el ejemplo siguiente, el método de convención Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put del tipo de convención predeterminada 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 método de convención Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put aplica los siguientes atributos a la acción:

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

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

  2. Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute aplicado a un controlador: se 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 este se aplica. Para obtener 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: se aplica el tipo de convención especificado a todos los controladores del ensamblado actual. Se recomienda aplicar atributos de nivel de ensamblado al archivo Startup.cs.

    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 no se presentan atributos de metadatos más específicos, la aplicación de esta convención a un ensamblado requiere lo siguiente:

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

Requisitos de nomenclatura

Los atributos [ApiConventionNameMatch] y [ApiConventionTypeMatch] pueden aplicarse 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 opción Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Prefix aplicada al método indica que la convención coincide con cualquier acción que vaya precedida de "Búsqueda". Entre los ejemplos de acciones coincidentes se incluyen Find, FindPet y FindById.
  • El valor Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Suffix aplicado al parámetro indica que la convención coincide con los métodos que tengan exactamente un parámetro que termine con el identificador del sufijo. Entre los ejemplos se incluyen parámetros tales como id o petId. ApiConventionTypeMatch puede aplicarse de forma similar a los tipos para restringir el tipo de parámetro. Un argumento params[] indica los parámetros restantes que no tienen que coincidir explícitamente.

Recursos adicionales