Partilhar via

Usar convenções de API da Web

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

Uma convenção permite-lhe:

  • Defina os tipos de retorno mais comuns e os códigos de status retornados de um tipo específico de ação.
  • Identificar 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 no 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 da Web.

Durante a execução, Microsoft.AspNetCore.Mvc.ApiExplorer compreende convenções. ApiExplorer é a abstração do MVC para se comunicar com geradores de documentos OpenAPI (também conhecido como Swagger). Os atributos da convenção aplicada são associados a uma ação e estão incluídos na documentação 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 retorna 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.

Visualizar ou descarregar amostra de código (como descarregar)

Aplicar convenções de API da Web

As convenções não compõem; Cada ação pode estar associada a exatamente uma convenção. As convenções mais específicas têm precedência sobre as 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 aplicável.

    No exemplo a seguir, o método de convenção do tipo de convenção padrão 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 da 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 uma assemblagem — Aplica o tipo de convenção especificado a todos os controladores na atual assemblagem. 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 da 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 estiverem ausentes atributos de metadados mais específicos, aplicar esta convenção a um assembly impõe que:

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

Requisitos de nomenclatura

Os [ApiConventionNameMatch] atributos e [ApiConventionTypeMatch] podem ser aplicados ao método de convenção que determina as ações às quais 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 "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 aos métodos com exatamente um parâmetro que termina no identificador de sufixo. Os exemplos incluem parâmetros como id ou petId. ApiConventionTypeMatch pode ser aplicado de forma semelhante a tipos para restringir o tipo de parâmetro. Um params[] argumento indica os parâmetros restantes que não precisam ser correspondidos explicitamente.

Recursos adicionais

  • Last updated on