Compartilhar via

Usar convenções de API Web

A documentação comum da API pode ser extraída e aplicada a várias ações, controladores ou todos os controladores em um assembly. As convenções de API Web substituem a decoração de ações individuais com [ProducesResponseType].

Uma convenção permite que você:

  • Defina os tipos de retorno mais comuns e os códigos de status retornados de um tipo específico de ação.
  • Identifique as ações que se desviam do padrão definido.

As convenções padrão estão disponíveis em Microsoft.AspNetCore.Mvc.DefaultApiConventions. As convenções são demonstradas com o ValuesController.cs adicionado a um modelo de projeto 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)
        {
        }
    }
}

Ações que seguem os padrões do ValuesController.cs funcionam com as convenções padrão. Se as convenções padrão não atenderem às suas necessidades, consulte Criar convenções de API Web.

Em runtime, Microsoft.AspNetCore.Mvc.ApiExplorer entende as convenções. ApiExplorer é a abstração do MVC para se comunicar com geradores de documentos OpenAPI (também conhecidos como Swagger). Os atributos da convenção aplicada são associados a uma ação e estão incluídos na documentação do OpenAPI da ação. Os analisadores de API também entendem as convenções. Se sua ação não for convencional (por exemplo, ela retornará um código de status que não está documentado pela convenção aplicada), um aviso incentiva você a documentar o código de status.

Exibir ou baixar código de exemplo (como baixar)

Aplicar convenções de API Web

As convenções não compõem; cada ação pode estar associada a exatamente uma convenção. Convenções mais específicas têm precedência sobre convenções menos específicas. A seleção não é determinística quando duas ou mais convenções da mesma prioridade se aplicam a uma ação. Existem as seguintes opções para aplicar uma convenção a uma ação, da mais específica à menos específica:

  1. Microsoft.AspNetCore.Mvc.ApiConventionMethodAttribute — Aplica-se a ações individuais e especifica o tipo de convenção e o método de convenção que se aplica.

    No exemplo a seguir, o método de convenção da convenção padrão do tipo de Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put é aplicado à ação 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();
}

    O Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put método de convenção aplica os seguintes atributos à ação:

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

    Para obter mais informações sobre [ProducesDefaultResponseType], consulte Resposta Padrão.

  2. Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute aplicado a um controlador – aplica o tipo de convenção especificado a todas as ações no controlador. Um método de convenção é marcado com dicas que determinam as ações às quais o método de convenção se aplica. Para obter mais informações sobre dicas, consulte Criar convenções de API Web).

    No exemplo a seguir, o conjunto padrão de convenções é aplicado a todas as ações em ContactsConventionController:

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

  3. Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute aplicado a um assembly – aplica o tipo de convenção especificado a todos os controladores no assembly atual. Como recomendação, aplique atributos de nível de assembly no arquivo Startup.cs.

    No exemplo a seguir, o conjunto padrão de convenções é aplicado a todos os controladores no assembly:

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

Criar convenções de API Web

Se as convenções de API padrão não atenderem às suas necessidades, crie suas próprias convenções. Uma convenção é:

Tipos de resposta

Esses métodos são anotados com [ProducesResponseType] ou [ProducesDefaultResponseType] atributos. Por exemplo:

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

Se atributos de metadados mais específicos estiverem ausentes, aplicar essa convenção a um assembly assegura que:

  • O método de convenção se aplica a qualquer ação chamada Find.
  • Um parâmetro nomeado id está presente na ação Find .

Requisitos de nomenclatura

Os atributos [ApiConventionNameMatch] e [ApiConventionTypeMatch] podem ser aplicados ao método convencional que determina as ações às quais eles se aplicam. Por exemplo:

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

No exemplo anterior:

  • A Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Prefix opção aplicada ao método indica que a convenção corresponde a qualquer ação prefixada com "Localizar". Exemplos de ações correspondentes incluem Find, FindPete FindById.
  • O Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Suffix aplicado ao parâmetro indica que a convenção corresponde aos métodos com exatamente um parâmetro que termina no identificador de sufixo. Exemplos incluem parâmetros como id ou petId. ApiConventionTypeMatch pode ser aplicado de forma semelhante aos tipos para restringir o tipo de parâmetro. Um params[] argumento indica os parâmetros restantes que não precisam ser explicitamente correspondidos.

Recursos adicionais

  • Last updated on