Utiliser les conventions d’API web

Article
11/30/2023

La documentation d’API courante peut être extraite et appliquée à plusieurs actions, contrôleurs ou tous les contrôleurs au sein d’un assembly. Les conventions des API web sont un substitut permettant de décorer des actions individuelles avec [ProducesResponseType].

Une convention vous permet de :

Définir les types de retours les plus courants et les codes d’état retournés à partir d’un type d’action spécifique.
Identifier les actions qui s’écartent de la norme définie.

Les conventions par défaut sont disponibles à partir de Microsoft.AspNetCore.Mvc.DefaultApiConventions. Les conventions sont illustrées avec le ValuesController.cs ajouté à un modèle de projet d’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)
        {
        }
    }
}

Les actions qui suivent les modèles du ValuesController.cs fonctionnent avec les conventions par défaut. Si les conventions par défaut ne répondent pas à vos besoins, consultez Créer des conventions d’API web.

À l’exécution, Microsoft.AspNetCore.Mvc.ApiExplorer comprend les conventions. ApiExplorer est l’abstraction de MVC pour communiquer avec des générateurs de documents OpenAPI (également nommé Swagger). Les attributs provenant de la convention appliquée sont associés à une action et sont inclus dans la documentation OpenAPI de l’action. Les analyseurs d’API comprennent aussi les conventions. Si votre action n’est pas conventionnelle (par exemple, elle retourne un code d’état qui n’est pas documenté par la convention appliquée), un avertissement vous encourage à documenter le code d’état.

Affichez ou téléchargez l’exemple de code (procédure de téléchargement)

Appliquer des conventions d’API web

Les conventions ne se combinent pas : chaque action peut être associée à une seule convention. Les conventions plus spécifiques sont prioritaires par rapport à celles qui sont moins spécifiques. La sélection est non déterministe quand plusieurs conventions de même priorité s’appliquent à une action. Les options suivantes sont disponibles pour appliquer une convention à une action, de la plus spécifique à la moins spécifique :

Microsoft.AspNetCore.Mvc.ApiConventionMethodAttribute — s’applique à des actions individuelles, et spécifie le type de convention et la méthode de convention qui s’applique.

Dans l’exemple suivant, la méthode de convention Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put du type de convention par défaut est appliquée à l’action 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();
}

La méthode de convention Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put applique les attributs suivants à l’action :

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

Pour plus d’informations sur [ProducesDefaultResponseType], consultez Réponse par défaut.

Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute appliqué à un contrôleur — applique le type de convention spécifié à toutes les actions sur le contrôleur. Une méthode de convention est marquée avec des indicateurs qui déterminent les actions auxquelles la méthode de convention s’applique. Pour plus d’informations sur les indicateurs, consultez Créer des conventions d’API web).

Dans l’exemple suivant, l’ensemble de conventions par défaut est appliqué à toutes les actions dans ContactsConventionController :
```
[ApiController]
[ApiConventionType(typeof(DefaultApiConventions))]
[Route("api/[controller]")]
public class ContactsConventionController : ControllerBase
{
```
Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute appliqué à un assembly — applique le type de convention spécifié à tous les contrôleurs dans l’assembly actif. Il est recommandé d’appliquer des attributs de niveau assembly dans le fichier Startup.cs.

Dans l’exemple suivant, l’ensemble de conventions par défaut est appliqué à tous les contrôleurs dans l’assembly :
```
[assembly: ApiConventionType(typeof(DefaultApiConventions))]
namespace ApiConventions
{
    public class Startup
    {
```

Créer des conventions d’API web

Si les conventions d’API par défaut ne répondent pas à vos besoins, créez vos propres conventions. Une convention est :

Un type statique avec des méthodes.
Capable de définir des types de réponse et des exigences de noms sur les actions.

Types de réponse

Ces méthodes sont annotées avec des attributs [ProducesResponseType] ou [ProducesDefaultResponseType]. Par exemple :

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

Si des attributs de métadonnées plus spécifiques sont absents, l’application de cette convention à un assembly considère que :

La méthode de convention s’applique à toute action nommée Find.
Un paramètre nommé id est présent sur l’action Find.

Conditions de nommage

Les attributs [ApiConventionNameMatch] et [ApiConventionTypeMatch] peuvent être appliqués à la méthode de convention qui détermine les actions auxquelles ils s’appliquent. Par exemple :

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

Dans l’exemple précédent :

L’option Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Prefix appliquée à la méthode indique que la convention correspond à n’importe action préfixée par « Find ». Les exemples d’actions correspondantes incluent Find, FindPet, et FindById.
Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Suffix appliqué au paramètre indique que la convention correspond aux méthodes avec un seul paramètre se terminant par l’identificateur du suffixe. Les exemples incluent des paramètres comme id ou petId. ApiConventionTypeMatch peut être appliqué de façon similaire à des types pour contraindre le type du paramètre. Un argument params[] indique les paramètres restants pour lesquels une correspondance explicite n’est pas nécessaire.