Sdílet prostřednictvím

Použití konvencí webového rozhraní API

  • Článek

Dokumentace k rozhraní API se dá extrahovat a použít u více akcí, kontrolerů nebo všech kontrolerů v rámci sestavení. Konvence webového rozhraní API jsou náhradou za dekódování jednotlivých akcí pomocí [ProducesResponseType].

Konvence umožňuje:

  • Definujte nejběžnější návratové typy a stavové kódy vrácené z konkrétního typu akce.
  • Identifikujte akce, které se odchylují od definovaného standardu.

Výchozí konvence jsou k dispozici na webu Microsoft.AspNetCore.Mvc.DefaultApiConventions. Konvence jsou demonstrována s přidanou ValuesController.cs šablonou projektu rozhraní 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)
        {
        }
    }
}

Akce, které se řídí vzory v ValuesController.cs práci s výchozími konvencemi Pokud výchozí konvence nevyhovují vašim potřebám, přečtěte si téma Vytváření konvencí webového rozhraní API.

Za běhu Microsoft.AspNetCore.Mvc.ApiExplorer rozumí konvencím. ApiExplorer je abstrakce MVC pro komunikaci s generátory dokumentů OpenAPI (označovanými také jako Swagger). Atributy z použité konvence jsou přidružené k akci a jsou zahrnuty do dokumentace k OpenAPI akce. Analyzátory rozhraní API také rozumí konvencím. Pokud je vaše akce nekonvenční (například vrátí stavový kód, který není zdokumentovaný použitou konvencí), upozornění vás vyzývá k dokumentaci stavového kódu.

Zobrazení nebo stažení ukázkového kódu (postup stažení)

Použití konvencí webového rozhraní API

Konvence se nevykládají; každá akce může být přidružená přesně k jedné konvenci. Konkrétnější konvence mají přednost před méně specifickými konvencemi. Výběr není deterministický, pokud se na akci vztahují dvě nebo více konvencí stejné priority. Existují následující možnosti, které použijí konvenci na akci, od nejvýraznějšího po nejméně konkrétní:

  1. Microsoft.AspNetCore.Mvc.ApiConventionMethodAttribute — Vztahuje se na jednotlivé akce a určuje typ konvence a metodu konvence, která se vztahuje.

    V následujícím příkladu se na akci použije Update metoda konvence výchozího typu Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put konvence:

    // 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();
}

    Metoda Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put konvence aplikuje na akci následující atributy:

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

    Další informace najdete [ProducesDefaultResponseType]v tématu Výchozí odpověď.

  2. Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute u kontroleru – použije zadaný typ konvence na všechny akce na kontroleru. Metoda konvence je označena radami, které určují akce, na které se metoda konvence vztahuje. Další informace o tipech najdete v tématu Vytváření konvencí webového rozhraní API).

    V následujícím příkladu je výchozí sada konvencí použita pro všechny akce v ContactsConventionController:

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

  3. Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute použité na sestavení — Použije zadaný typ konvence pro všechny kontrolery v aktuálním sestavení. Jako doporučení použijte v Startup.cs souboru atributy na úrovni sestavení.

    V následujícím příkladu se výchozí sada konvencí použije na všechny kontrolery v sestavení:

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

Vytváření konvencí webového rozhraní API

Pokud výchozí konvence rozhraní API nevyhovují vašim potřebám, vytvořte vlastní konvence. Konvence je:

  • Statický typ s metodami.
  • Dokáže definovat typy odpovědí a požadavky na pojmenování akcí.

Typy odpovědí

Tyto metody jsou opatřeny poznámkami [ProducesResponseType] nebo [ProducesDefaultResponseType] atributy. Příklad:

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

Pokud chybí konkrétnější atributy metadat, použití této konvence na sestavení vynutí, že:

  • Metoda konvence se vztahuje na jakoukoli akci s názvem Find.
  • V akci se nachází Find parametr s názvemid.

Požadavky na pojmenování

[ApiConventionTypeMatch] U [ApiConventionNameMatch] metody konvence lze použít atributy, které určují akce, na které se vztahují. Příklad:

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

V předchozím příkladu:

  • Možnost Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Prefix použitá u metody označuje, že konvence odpovídá jakékoli akci s předponou "Najít". Mezi příklady odpovídajících akcí patří Find, FindPeta FindById.
  • Použité Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Suffix na parametr označuje, že konvence odpovídá metodám s přesně jedním parametrem končícím identifikátorem přípony. Příklady zahrnují parametry, například id nebo petId. ApiConventionTypeMatch lze podobně použít u typů pro omezení typu parametru. Argument params[] označuje zbývající parametry, které se nemusí explicitně shodovat.

Další prostředky