Partager via

Utiliser des conventions d’API web

La documentation d’API commune peut être extraite et appliquée à plusieurs actions, contrôleurs ou tous les contrôleurs d’un assembly. Les conventions d’API web sont un substitut à la décoration d’actions individuelles avec [ProducesResponseType].

Une convention vous permet de :

  • Définissez les types de retour et les codes d’état les plus courants retournés à partir d’un type d’action spécifique.
  • Identifiez 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 l’ajout ValuesController.cs à 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)
        {
        }
    }
}

Actions qui suivent les modèles du ValuesController.cs travail 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.

Au moment de l’exécution, Microsoft.AspNetCore.Mvc.ApiExplorer comprend les conventions. ApiExplorer est l’abstraction de MVC pour communiquer avec les générateurs de documents OpenAPI (également appelés Swagger). Les attributs 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 également 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 composent pas ; chaque action peut être associée à exactement une convention. Les conventions plus spécifiques sont prioritaires sur les conventions moins spécifiques. La sélection n’est pas déterministe quand deux ou plusieurs conventions de la même priorité s’appliquent à une action. Les options suivantes permettent d’appliquer une convention à une action, du plus spécifique au moins spécifique :

  1. 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 par défaut du Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put type de convention 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 Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put méthode de convention 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.

  2. 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
{

  3. Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute appliqué à un assembly : applique le type de convention spécifié à tous les contrôleurs de l’assembly actuel. À titre de recommandation, appliquez des attributs au niveau de l’assembly dans le Startup.cs fichier.

    Dans l’exemple suivant, l’ensemble de conventions par défaut est appliqué à tous les contrôleurs de 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 la suivante :

Types de réponse

Ces méthodes sont annotées avec [ProducesResponseType] ou [ProducesDefaultResponseType] attributs. 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 applique ce qui suit :

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

Exigences en matière de nommage

Les [ApiConventionNameMatch] attributs et [ApiConventionTypeMatch] les attributs peuvent être appliqués à la méthode de convention qui détermine les actions auxquelles elles 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 à toute action précédée de « Find ». Exemples d’actions correspondantes : , FindFindPetet FindById.
  • L’application Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Suffix au paramètre indique que la convention correspond aux méthodes avec exactement un paramètre se terminant par l’identificateur de suffixe. Les exemples incluent des paramètres tels que id ou petId. ApiConventionTypeMatch peut être appliqué de la même façon aux types pour limiter le type de paramètre. Un params[] argument indique les paramètres restants qui n’ont pas besoin d’être explicitement mis en correspondance.

Ressources supplémentaires

  • Last updated on