Sdílet prostřednictvím

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

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 dekorová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ány přidáním ValuesController.cs k šabloně projektu 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, pracují 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.

Při 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. Následující možnosti slouží k aplikaci konvence na akci, od nejkonkrétnějšího po nejméně specifické:

  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 je na akci Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put aplikována metoda výchozího typu konvence 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();
}

    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 o [ProducesDefaultResponseType] najdete v části 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 aplikované 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:

Typy odpovědí

Tyto metody jsou opatřeny poznámkami [ProducesResponseType] nebo [ProducesDefaultResponseType] atributy. Napří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í tohoto pravidla na sestavení zajistí, že:

  • Metoda konvence se vztahuje na jakoukoli akci s názvem Find.
  • V akci id je přítomen parametr s názvem Find.

Požadavky na pojmenování

Na metodu konvence lze aplikovat atributy [ApiConventionNameMatch] a [ApiConventionTypeMatch], které určují akce, na které se vztahují. Napří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.

Dodatečné zdroje

  • Last updated on