Usar convenções de API WebUse web API conventions

Por Pranav Krishnamoorthy e Scott AddieBy Pranav Krishnamoorthy and Scott Addie

O ASP.NET Core 2.2 (e posterior) inclui uma forma de extrair a documentação da API comum e aplicá-la a várias ações, controladores ou a todos os controladores em um assembly.ASP.NET Core 2.2 and later includes a way to extract common API documentation and apply it to multiple actions, controllers, or all controllers within an assembly. As convenções de API Web são um substituto para ambientar as ações individuais com [ProducesResponseType].Web API conventions are a substitute for decorating individual actions with [ProducesResponseType].

Uma convenção permite que você:A convention allows you to:

  • Defina os tipos de retorno mais comuns e códigos de status retornados de um tipo de ação específico.Define the most common return types and status codes returned from a specific type of action.
  • Identifica as ações que desviam do padrão definido.Identify actions that deviate from the defined standard.

O ASP.NET Core MVC 2.2 (e posterior) inclui um conjunto de convenções padrão em Microsoft.AspNetCore.Mvc.DefaultApiConventions.ASP.NET Core MVC 2.2 and later includes a set of default conventions in Microsoft.AspNetCore.Mvc.DefaultApiConventions. As convenções são baseadas no controlador (ValuesController.cs) fornecido no modelo de projeto da API do ASP.NET Core.The conventions are based on the controller (ValuesController.cs) provided in the ASP.NET Core API project template. Se suas ações seguem o padrão no modelo, você deve ter êxito ao usar as convenções padrão.If your actions follow the patterns in the template, you should be successful using the default conventions. Se as convenções padrão não atenderem às suas necessidades, consulte Criar convenções de API Web.If the default conventions don't meet your needs, see Create web API conventions.

No tempo de execução, Microsoft.AspNetCore.Mvc.ApiExplorer reconhece as convenções.At runtime, Microsoft.AspNetCore.Mvc.ApiExplorer understands conventions. ApiExplorer é a abstração do MVC para comunicação com geradores de documento da OpenAPI (também conhecida como Swagger).ApiExplorer is MVC's abstraction to communicate with OpenAPI (also known as Swagger) document generators. 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.Attributes from the applied convention are associated with an action and are included in the action's OpenAPI documentation. Os Analisadores de API também reconhecem as convenções.API analyzers also understand conventions. 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.If your action is unconventional (for example, it returns a status code that isn't documented by the applied convention), a warning encourages you to document the status code.

Exibir ou baixar código de exemplo (como baixar)View or download sample code (how to download)

Aplicar convenções de API WebApply web API conventions

As convenções não fazem composição. Cada ação pode ser associada a exatamente uma convenção.Conventions don't compose; each action may be associated with exactly one convention. As convenções mais específicas têm precedência sobre as menos específicas.More specific conventions take precedence over less specific conventions. A seleção é não determinística quando duas ou mais convenções da mesma prioridade se aplicam a uma ação.The selection is non-deterministic when two or more conventions of the same priority apply to an action. As seguintes opções existem para aplicar uma convenção a uma ação, da mais específica à menos específica:The following options exist to apply a convention to an action, from the most specific to the least specific:

  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.Microsoft.AspNetCore.Mvc.ApiConventionMethodAttribute — Applies to individual actions and specifies the convention type and the convention method that applies.

    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:In the following example, the default convention type's Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put convention method is applied to the Update action:

    // 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:The Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put convention method applies the following attributes to the action:

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

    Para saber mais sobre [ProducesDefaultResponseType], confira Resposta padrão.For more information on [ProducesDefaultResponseType], see Default Response.

  2. Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute aplicado a um controlador —. Aplica-se o tipo de convenção especificada a todas as ações no controlador.Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute applied to a controller — Applies the specified convention type to all actions on the controller. Um método de convenção é decorado com dicas que determinam as ações às quais o método de convenção se aplica.A convention method is decorated with hints that determine the actions to which the convention method applies. Para obter mais informações sobre dicas, consulte Criar convenções da API Web).For more information on hints, see Create web API conventions).

    No exemplo a seguir, o conjunto padrão de convenções é aplicado a todas as ações no ContactsConventionController:In the following example, the default set of conventions is applied to all actions in ContactsConventionController:

    [ApiController]
    [ApiConventionType(typeof(DefaultApiConventions))]
    [Route("api/[controller]")]
    public class ContactsConventionController : ControllerBase
    {
    
  3. Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute aplicado a um assembly —. Aplica-se o tipo de convenção especificada a todos os controladores no assembly atual.Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute applied to an assembly — Applies the specified convention type to all controllers in the current assembly. Como recomendação, aplique atributos no nível do assembly ao arquivo Startup.cs.As a recommendation, apply assembly-level attributes in the Startup.cs file.

    No exemplo a seguir, o conjunto padrão de convenções é aplicado a todos os controladores no assembly:In the following example, the default set of conventions is applied to all controllers in the assembly:

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

Criar convenções de API WebCreate web API conventions

Se as convenções padrão da API não atenderem às suas necessidades, crie suas próprias convenções.If the default API conventions don't meet your needs, create your own conventions. Uma convenção é:A convention is:

Tipos de respostaResponse types

Esses métodos são anotados com atributos [ProducesResponseType] ou [ProducesDefaultResponseType].These methods are annotated with [ProducesResponseType] or [ProducesDefaultResponseType] attributes. Por exemplo:For example:

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:If more specific metadata attributes are absent, applying this convention to an assembly enforces that:

  • O método de convenção se aplica a qualquer ação denominada Find.The convention method applies to any action named Find.
  • Um parâmetro denominado id está presente na ação Find.A parameter named id is present on the Find action.

Requisitos de nomenclaturaNaming requirements

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.The [ApiConventionNameMatch] and [ApiConventionTypeMatch] attributes can be applied to the convention method that determines the actions to which they apply. Por exemplo:For example:

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

No exemplo anterior:In the preceding example:

  • 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".The Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Prefix option applied to the method indicates that the convention matches any action prefixed with "Find". Exemplos de ações correspondentes incluem Find, FindPet e FindById.Examples of matching actions include Find, FindPet, and 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.The Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Suffix applied to the parameter indicates that the convention matches methods with exactly one parameter ending in the suffix identifier. Exemplos incluem parâmetros como id ou petId.Examples include parameters such as id or petId. ApiConventionTypeMatch pode ser aplicado da mesma forma aos tipos para restringir o tipo do parâmetro.ApiConventionTypeMatch can be similarly applied to types to constrain the parameter type. Um argumento params[] indica parâmetros restantes que não precisam ser explicitamente correspondidos.A params[] argument indicates remaining parameters that don't need to be explicitly matched.

Recursos adicionaisAdditional resources