Condividi tramite

Usare le convenzioni dell'API Web

La documentazione dell'API comune può essere estratta e applicata a più azioni, controller o tutti i controller all'interno di un assembly. Le convenzioni dell'API Web sono un sostituto per la decorazione di singole azioni con [ProducesResponseType].

Una convenzione consente di:

  • Definire i tipi restituiti e i codici di stato più comuni restituiti da un tipo specifico di azione.
  • Identificare le azioni che si discostono dallo standard definito.

Le convenzioni predefinite sono disponibili da Microsoft.AspNetCore.Mvc.DefaultApiConventions. Le convenzioni vengono illustrate con l'aggiunta ValuesController.cs a un modello di progetto 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)
        {
        }
    }
}

Azioni che seguono i modelli nel ValuesController.cs lavoro con le convenzioni predefinite. Se le convenzioni predefinite non soddisfano le proprie esigenze, vedere Creare convenzioni api Web.

In fase di esecuzione, Microsoft.AspNetCore.Mvc.ApiExplorer comprende le convenzioni. ApiExplorer è l'astrazione di MVC per comunicare con i generatori di documenti OpenAPI (noti anche come Swagger). Gli attributi della convenzione applicata sono associati a un'azione e sono inclusi nella documentazione OpenAPI dell'azione. Gli analizzatori API comprendono anche le convenzioni. Se l'azione non è convenzionale (ad esempio, restituisce un codice di stato non documentato dalla convenzione applicata), un avviso invita a documentare il codice di stato.

Visualizzare o scaricare il codice di esempio (come scaricare)

Applicare convenzioni api Web

Le convenzioni non compongono; ogni azione può essere associata esattamente a una convenzione. Le convenzioni più specifiche hanno la precedenza su convenzioni meno specifiche. La selezione non è deterministica quando due o più convenzioni della stessa priorità si applicano a un'azione. Esistono le opzioni seguenti per applicare una convenzione a un'azione, dal più specifico al meno specifico:

  1. Microsoft.AspNetCore.Mvc.ApiConventionMethodAttribute — Si applica alle singole azioni e specifica il tipo di convenzione e il metodo di convenzione applicabile.

    Nell'esempio seguente il metodo convenzione del Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put tipo di convenzione predefinito viene applicato all'azione 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();
}

    Il Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put metodo convention applica gli attributi seguenti all'azione:

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

    Per altre informazioni su [ProducesDefaultResponseType], vedere Risposta predefinita.

  2. Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute applicato a un controller : applica il tipo di convenzione specificato a tutte le azioni nel controller. Un metodo di convenzione è contrassegnato con hint che determinano le azioni a cui si applica il metodo della convenzione. Per altre informazioni sugli hint, vedere Creare convenzioni api Web.

    Nell'esempio seguente il set predefinito di convenzioni viene applicato a tutte le azioni in ContactsConventionController:

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

  3. Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute applicato a un assembly : applica il tipo di convenzione specificato a tutti i controller nell'assembly corrente. Come raccomandazione, applicare attributi a livello di assembly nel Startup.cs file.

    Nell'esempio seguente il set predefinito di convenzioni viene applicato a tutti i controller nell'assembly:

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

Creare convenzioni api Web

Se le convenzioni API predefinite non soddisfano le proprie esigenze, creare convenzioni personalizzate. Una convenzione è:

Tipi di risposta

Questi metodi vengono annotati con [ProducesResponseType] attributi o [ProducesDefaultResponseType] . Per esempio:

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

Se gli attributi di metadati più specifici sono assenti, l'applicazione di questa convenzione a un assembly impone che:

  • Il metodo della convenzione si applica a qualsiasi azione denominata Find.
  • Un parametro denominato id è presente nell'azione Find .

Requisiti di denominazione

Gli attributi [ApiConventionNameMatch] e [ApiConventionTypeMatch] possono essere applicati al metodo di convenzione che determina le azioni a cui si applicano. Per esempio:

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

Nell'esempio precedente:

  • L'opzione Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Prefix applicata al metodo indica che la convenzione corrisponde a qualsiasi azione preceduta da "Trova". Esempi di azioni di corrispondenza includono Find, FindPete FindById.
  • L'oggetto Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Suffix applicato al parametro indica che la convenzione corrisponde ai metodi con esattamente un parametro che termina nell'identificatore del suffisso. Gli esempi includono parametri come id o petId. ApiConventionTypeMatch può essere applicato in modo analogo ai tipi per vincolare il tipo di parametro. Un params[] argomento indica gli altri parametri che non devono essere esplicitamente corrispondenti.

Risorse aggiuntive

  • Last updated on