Dela via

Använda webb-API-konventioner

Gemensam API-dokumentation kan extraheras och tillämpas på flera åtgärder, kontrollanter eller alla kontrollanter i en sammansättning. Webb-API-konventioner ersätter att dekorera enskilda åtgärder med [ProducesResponseType].

Med en konvention kan du:

  • Definiera de vanligaste returtyperna och statuskoderna som returneras från en viss typ av åtgärd.
  • Identifiera åtgärder som avviker från den definierade standarden.

Standardkonventioner är tillgängliga från Microsoft.AspNetCore.Mvc.DefaultApiConventions. Konventionerna demonstreras med ValuesController.cs som har lagts till i en API-projektmall:

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)
        {
        }
    }
}

Åtgärder som följer mönstren i ValuesController.cs arbetar med standardkonventionerna. Om standardkonventionerna inte uppfyller dina behov kan du läsa Skapa webb-API-konventioner.

Vid körning Microsoft.AspNetCore.Mvc.ApiExplorer förstår konventioner. ApiExplorer är MVC:s abstraktion för att kommunicera med OpenAPI-dokumentgeneratorer (även kallade Swagger). Attribut från den tillämpade konventionen är associerade med en åtgärd och ingår i åtgärdens OpenAPI-dokumentation. API-analysatorer förstår också konventioner. Om åtgärden är okonventionell (till exempel returnerar den en statuskod som inte dokumenteras av den tillämpade konventionen), uppmanar en varning dig att dokumentera statuskoden.

Visa eller ladda ned exempelkod (hur du laddar ned)

Tillämpa webb-API-konventioner

Konventioner är inte sammansatta. varje åtgärd kan associeras med exakt en konvention. Mer specifika konventioner har företräde framför mindre specifika konventioner. Valet är icke-deterministiskt när två eller flera konventioner med samma prioritet gäller för en åtgärd. Följande alternativ finns för att tillämpa en konvention på en åtgärd, från den mest specifika till den minst specifika:

  1. Microsoft.AspNetCore.Mvc.ApiConventionMethodAttribute – Gäller för enskilda åtgärder och anger konventionstypen och den konventionsmetod som gäller.

    I följande exempel tillämpas standardregeltypens Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put konventionsmetod på åtgärden 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();
}

    Konventionsmetoden Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put tillämpar följande attribut på åtgärden:

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

    Mer information om [ProducesDefaultResponseType]finns i Standardsvar.

  2. Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute tillämpas på en controller – Tillämpar den angivna konventionstypen på alla åtgärder på controllern. En konventionsmetod markeras med tips som avgör vilka åtgärder som konventionsmetoden gäller för. Mer information om tips finns i Skapa webb-API-konventioner).

    I följande exempel tillämpas standarduppsättningen med konventioner på alla åtgärder i ContactsConventionController:

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

  3. Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute tillämpas på en sammansättning – Tillämpar den angivna konventionstypen på alla kontrollanter i den aktuella sammansättningen. Som rekommendation bör du använda attribut på monteringsnivå i Startup.cs-filen.

    I följande exempel tillämpas standarduppsättningen med konventioner på alla kontrollanter i sammansättningen:

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

Skapa webb-API-konventioner

Om standard-API-konventionerna inte uppfyller dina behov skapar du dina egna konventioner. En konvention är:

Svarstyper

Dessa metoder kommenteras med [ProducesResponseType] eller [ProducesDefaultResponseType] attribut. Till exempel:

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

Den här konventionen tillämpas på en sammansättning om mer specifika metadataattribut saknas:

  • Konventionsmetoden gäller för alla åtgärder med namnet Find.
  • En parameter med namnet id finns på åtgärden Find .

Namngivningskrav

Attributen [ApiConventionNameMatch] och [ApiConventionTypeMatch] kan tillämpas på den konventionsmetod som avgör vilka åtgärder de gäller för. Till exempel:

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

I föregående exempel:

  • Alternativet Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Prefix som tillämpas på metoden anger att konventionen matchar alla åtgärder som har prefixet "Find". Exempel på matchande åtgärder är Find, FindPetoch FindById.
  • Den Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Suffix som tillämpas på parametern anger att konventionen matchar metoder med exakt en parameter som slutar i suffixidentifieraren. Exempel är parametrar som id eller petId. ApiConventionTypeMatch kan tillämpas på liknande sätt på typer för att begränsa parametertypen. Ett params[] argument anger återstående parametrar som inte behöver matchas explicit.

Ytterligare resurser