Używanie konwencji internetowego interfejsu API

  • Artykuł

Typową dokumentację interfejsu API można wyodrębnić i zastosować do wielu akcji, kontrolerów lub wszystkich kontrolerów w zestawie. Konwencje internetowego interfejsu API są zamiennikiem dekorowania poszczególnych akcji za pomocą polecenia [ProducesResponseType].

Konwencja umożliwia:

  • Zdefiniuj najczęstsze typy zwracane i kody stanu zwrócone z określonego typu akcji.
  • Identyfikowanie akcji, które odbiegają od zdefiniowanego standardu.

Konwencje domyślne są dostępne w witrynie Microsoft.AspNetCore.Mvc.DefaultApiConventions. Konwencje są przedstawiane z ValuesController.cs dodanym do szablonu projektu interfejsu 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)
        {
        }
    }
}

Akcje, które są zgodne ze wzorcami w ValuesController.cs pracy z konwencjami domyślnymi. Jeśli konwencje domyślne nie spełniają Twoich potrzeb, zobacz Tworzenie konwencji internetowego interfejsu API.

W czasie wykonywania Microsoft.AspNetCore.Mvc.ApiExplorer rozumie konwencje. ApiExplorer jest abstrakcją MVC do komunikowania się z generatorami dokumentów OpenAPI (znanym również jako Swagger). Atrybuty z zastosowanej konwencji są skojarzone z akcją i są uwzględnione w dokumentacji interfejsu OpenAPI akcji. Analizatory interfejsów API rozumieją również konwencje. Jeśli akcja jest niekonwencjonalna (na przykład zwraca kod stanu, który nie jest udokumentowany przez zastosowaną konwencję), ostrzeżenie zachęca do dokumentowania kodu stanu.

Wyświetl lub pobierz przykładowy kod (jak pobrać)

Stosowanie konwencji internetowego interfejsu API

Konwencje nie tworzą; każda akcja może być skojarzona z dokładnie jedną konwencją. Bardziej szczegółowe konwencje mają pierwszeństwo przed mniej specyficznymi konwencjami. Wybór nie jest deterministyczny, gdy co najmniej dwie konwencje tego samego priorytetu dotyczą akcji. Istnieją następujące opcje, aby zastosować konwencję do akcji, od najbardziej specyficznych do najmniej określonych:

  1. Microsoft.AspNetCore.Mvc.ApiConventionMethodAttribute — dotyczy poszczególnych akcji i określa typ konwencji i metodę konwencji, która ma zastosowanie.

    W poniższym przykładzie domyślna metoda konwencji typu Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put konwencji jest stosowana do Update akcji:

    // 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 konwencji stosuje następujące atrybuty do akcji:

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

    Aby uzyskać więcej informacji na temat [ProducesDefaultResponseType]programu , zobacz Odpowiedź domyślna.

  2. Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute zastosowane do kontrolera — stosuje określony typ konwencji do wszystkich akcji na kontrolerze. Metoda konwencji jest oznaczona wskazówkami określającymi akcje, do których stosuje się metodę konwencji. Aby uzyskać więcej informacji na temat wskazówek, zobacz Create web API conventions (Tworzenie konwencji internetowego interfejsu API).

    W poniższym przykładzie domyślny zestaw konwencji jest stosowany do wszystkich akcji w aplikacji ContactsConventionController:

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

  3. Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute zastosowane do zestawu — stosuje określony typ konwencji do wszystkich kontrolerów w bieżącym zestawie. Zgodnie z zaleceniem zastosuj atrybuty na poziomie zestawu w Startup.cs pliku.

    W poniższym przykładzie domyślny zestaw konwencji jest stosowany do wszystkich kontrolerów w zestawie:

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

Tworzenie konwencji internetowego interfejsu API

Jeśli domyślne konwencje interfejsu API nie spełniają Twoich potrzeb, utwórz własne konwencje. Konwencja to:

  • Typ statyczny z metodami.
  • Możliwość definiowania typów odpowiedzi i wymagań dotyczących nazewnictwa akcji.

Typy odpowiedzi

Te metody są oznaczone adnotacjami [ProducesResponseType] lub [ProducesDefaultResponseType] atrybutami. Przykład:

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

Jeśli bardziej szczegółowe atrybuty metadanych są nieobecne, zastosowanie tej konwencji do zestawu wymusza następujące elementy:

  • Metoda konwencji ma zastosowanie do dowolnej akcji o nazwie Find.
  • Parametr o nazwie id znajduje się w Find akcji.

Wymagania dotyczące nazewnictwa

Atrybuty [ApiConventionNameMatch] i [ApiConventionTypeMatch] można zastosować do metody konwencji, która określa akcje, do których mają zastosowanie. Przykład:

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

W poprzednim przykładzie:

  • Opcja zastosowana Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Prefix do metody wskazuje, że konwencja jest zgodna z dowolną akcją poprzedzoną prefiksem "Znajdź". Przykłady pasujących akcji to Find, FindPeti FindById.
  • Zastosowany Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Suffix do parametru wskazuje, że konwencja jest zgodna z metodami z dokładnie jednym parametrem kończącym się identyfikatorem sufiksu. Przykłady obejmują parametry, takie jak id lub petId. ApiConventionTypeMatch Można stosować podobnie do typów, aby ograniczyć typ parametru. params[] Argument wskazuje pozostałe parametry, które nie muszą być jawnie dopasowane.

Dodatkowe zasoby