Usar convenções de API Web

Artigo
11/30/2023

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

Uma convenção permite que você:

Defina os tipos de retorno mais comuns e códigos de status retornados de um tipo de ação específico.
Identifica as ações que 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)
        {
        }
    }
}

As ações que seguem os padrões no ValuesController.cs trabalham 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.

No runtime, Microsoft.AspNetCore.Mvc.ApiExplorer reconhece as convenções. ApiExplorer é a abstração do MVC para comunicação com geradores de documento da OpenAPI (também conhecida como Swagger). Os atributos da convenção aplicada são associados a uma ação e estão incluídos na documentação da OpenAPI da ação. Os Analisadores de API também reconhecem as convenções. Se a ação for não convencional (por exemplo, ela retorna um código de status que não está documentado pela convenção aplicada), um aviso incentivará você a fazer a documentação do código de status.

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

Aplicar convenções de API Web

As convenções não fazem composição. Cada ação pode ser associada a exatamente uma convenção. As convenções mais específicas têm precedência sobre as 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. As seguintes opções existem para aplicar uma convenção a uma ação, da mais específica à menos específica:

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 Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put do tipo de convenção padrão é 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 método de convenção Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put aplica os seguintes atributos à ação:

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

Para saber mais sobre [ProducesDefaultResponseType], confira Resposta padrão.

Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute aplicado a um controlador – aplica o tipo de convenção especificada 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 da API Web).

No exemplo a seguir, o conjunto padrão de convenções é aplicado a todas as ações no ContactsConventionController:
```
[ApiController]
[ApiConventionType(typeof(DefaultApiConventions))]
[Route("api/[controller]")]
public class ContactsConventionController : ControllerBase
{
```
Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute aplicado a um assembly – aplica o tipo de convenção especificada a todos os controladores no assembly atual. Como recomendação, aplique atributos no nível do 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 padrão da API não atenderem às suas necessidades, crie suas próprias convenções. Uma convenção é:

um tipo estático com métodos.
Com capacidade de definir tipos de resposta e requisitos de nomenclatura em ações.

Tipos de resposta

Esses métodos são anotados com atributos [ProducesResponseType] ou [ProducesDefaultResponseType]. 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 estão ausentes, a aplicação dessa convenção a um assembly impõe que:

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

Requisitos de nomenclatura

Os atributos [ApiConventionNameMatch] e [ApiConventionTypeMatch] podem ser aplicados ao método de convenção que determina as ações às quais eles são aplicáveis. Por exemplo:

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

No exemplo anterior:

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