Delen via

Web-API-conventies gebruiken

Algemene API-documentatie kan worden geëxtraheerd en toegepast op meerdere acties, controllers of alle controllers binnen een assembly. Web-API-conventies zijn een vervanging voor het decoreren van afzonderlijke acties met [ProducesResponseType].

Met een conventie kunt u het volgende doen:

  • Definieer de meest voorkomende retourtypen en statuscodes die worden geretourneerd door een specifiek type actie.
  • Identificeer acties die afwijken van de gedefinieerde standaard.

Standaardconventies zijn beschikbaar via Microsoft.AspNetCore.Mvc.DefaultApiConventions. De conventies worden gedemonstreerd met de ValuesController.cs toegevoegde aan een API-projectsjabloon :

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

Acties die de patronen in het ValuesController.cs werk volgen met de standaardconventies. Als de standaardconventies niet aan uw behoeften voldoen, raadpleegt u Web-API-conventies maken.

Tijdens runtime Microsoft.AspNetCore.Mvc.ApiExplorer begrijpt u conventies. ApiExploreris de abstractie van MVC om te communiceren met OpenAPI-documentgeneratoren (ook wel Swagger genoemd). Kenmerken van de toegepaste conventie zijn gekoppeld aan een actie en worden opgenomen in de OpenAPI-documentatie van de actie. API-analysen begrijpen ook conventies. Als uw actie onconventioneel is (bijvoorbeeld als er een statuscode wordt geretourneerd die niet wordt gedocumenteerd door de toegepaste conventie), wordt u aangemoedigd om de statuscode te documenteren.

Voorbeeldcode bekijken of downloaden (hoe download je)

Web-API-conventies toepassen

Conventies bestaan niet; elke actie kan worden gekoppeld aan precies één conventie. Specifiekere conventies hebben voorrang op minder specifieke conventies. De selectie is niet-deterministisch wanneer twee of meer conventies van dezelfde prioriteit van toepassing zijn op een actie. Er zijn de volgende opties om een conventie toe te passen op een actie, van de meest specifieke naar de minst specifieke:

  1. Microsoft.AspNetCore.Mvc.ApiConventionMethodAttribute — Is van toepassing op afzonderlijke acties en specificeert het conventietype en de conventiemethode die van toepassing is.

    In het volgende voorbeeld wordt de conventiemethode van Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put het standaardconventietype toegepast op de Update actie:

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

    De Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put conventiemethode past de volgende kenmerken toe op de actie:

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

    Zie Standaardantwoord voor meer informatie[ProducesDefaultResponseType].

  2. Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute toegepast op een controller : past het opgegeven conventietype toe op alle acties op de controller. Een conventiemethode wordt gemarkeerd met hints waarmee de acties worden bepaald waarop de conventiemethode van toepassing is. Zie Web-API-conventies maken voor meer informatie over hints.

    In het volgende voorbeeld wordt de standaardset conventies toegepast op alle acties in ContactsConventionController:

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

  3. Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute toegepast op een assembly : past het opgegeven conventietype toe op alle controllers in de huidige assembly. Pas als aanbeveling kenmerken op assemblyniveau toe in het Startup.cs bestand.

    In het volgende voorbeeld wordt de standaardset conventies toegepast op alle controllers in de assembly:

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

Web-API-conventies maken

Als de standaard-API-conventies niet aan uw behoeften voldoen, maakt u uw eigen conventies. Een conventie is:

Response types

Deze methoden worden geannoteerd met [ProducesResponseType] of [ProducesDefaultResponseType] kenmerken. For example:

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

Als er meer specifieke metagegevenskenmerken ontbreken, dwingt u deze conventie toe op een assembly om het volgende af te dwingen:

  • De conventiemethode is van toepassing op een actie met de naam Find.
  • Er is een parameter met de naam id aanwezig in de Find actie.

Naming requirements

De [ApiConventionNameMatch] kenmerken en [ApiConventionTypeMatch] kenmerken kunnen worden toegepast op de conventiemethode waarmee de acties worden bepaald waarop ze van toepassing zijn. For example:

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

In het voorgaande voorbeeld:

  • De Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Prefix optie die op de methode wordt toegepast, geeft aan dat de conventie overeenkomt met een actie die is voorafgegaan door 'Zoeken'. Voorbeelden van overeenkomende acties zijn Find, FindPeten FindById.
  • De Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Suffix toegepaste parameter geeft aan dat de conventie overeenkomt met methoden met precies één parameter die eindigt op de achtervoegsel-id. Voorbeelden zijn parameters zoals id of petId. ApiConventionTypeMatch kan op dezelfde manier worden toegepast op typen om het parametertype te beperken. Een params[] argument geeft de resterende parameters aan die niet expliciet hoeven te worden vergeleken.

Additional resources