Verwenden von Web-API-Konventionen

Artikel
11/30/2023

Die gemeinsame API-Dokumentation kann extrahiert und auf mehrere Aktionen, Controller oder alle Controller innerhalb einer Assembly angewendet werden. Web-API-Konventionen können verwendet werden, damit keine einzelnen Aktionen mit [ProducesResponseType] markiert werden müssen.

Eine Konvention ermöglicht Ihnen Folgendes:

Definieren der gebräuchlichsten Rückgabetypen und Statuscodes, die von einem bestimmten Typ von Aktion zurückgegeben werden
Erkennen von Aktionen, die vom definierten Standard abweichen

Standardkonventionen sind über Microsoft.AspNetCore.Mvc.DefaultApiConventions verfügbar. Die Konventionen werden mit dem ValuesController.cs, der zu einer API-Projektvorlage hinzugefügt wurde, veranschaulicht:

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

Aktionen, die den Mustern im ValuesController.cs folgen, arbeiten mit den Standardkonventionen. Wenn die Standardkonventionen Ihre Anforderungen nicht erfüllen, lesen Sie Erstellen von Web-API-Konventionen.

Microsoft.AspNetCore.Mvc.ApiExplorer erkennt zur Laufzeit Konventionen. ApiExplorer ist die Abstraktion von MVC, über die mit OpenAPI-Dokumentgeneratoren kommuniziert wird (OpenAPI ist auch als Swagger bekannt). Die Attribute aus der angewendeten Konvention werden einer Aktion zugeordnet und zur OpenAPI-Dokumentation der Aktion hinzugefügt. Auch API-Analysetools erkennen Konventionen. Wenn Ihre Aktion keiner Konvention folgt (also z. B. einen Statuscode zurückgibt, der nicht durch die angewendete Konvention dokumentiert ist), werden Sie mit einer Warnung aufgefordert, den Statuscode zu dokumentieren.

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)

Anwenden von Web-API-Konventionen

Konventionen werden nicht miteinander kombiniert. Jede Aktion kann genau einer Konvention zugeordnet werden. Speziellere Konventionen haben Vorrang vor weniger speziellen Konventionen. Die Auswahl ist nicht deterministisch, wenn mindestens zwei Konventionen mit gleicher Priorität für eine Aktion gelten. Sie können eine der folgenden Optionen auswählen, um angefangen bei der genausten Konvention bis hin zur ungenausten eine Konvention auf eine Aktion anzuwenden:

Microsoft.AspNetCore.Mvc.ApiConventionMethodAttribute: Gilt für einzelne Aktionen und gibt den jeweiligen passenden Konventionstyp und die Konventionsmethode an.

Im folgenden Beispiel wird die Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put-Konventionsmethode des Standardkonventionstyps auf die Update-Aktion angewendet:

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

Die Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put-Konventionsmethode wendet die folgenden Attribute auf die Aktion an:

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

Weitere Informationen zu [ProducesDefaultResponseType] finden Sie unter Standardantwort.

Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute, auf einen Controller angewendet: Wendet den angegebenen Konventionstyp auf alle Controlleraktionen an. Eine Konventionsmethode ist mit Hinweisen markiert, mit denen die Aktionen bestimmt werden, für die die Konventionsmethode gilt. Weitere Informationen zu Hinweisen finden Sie unter Erstellen von Web-API-Konventionen).

Im folgenden Beispiel werden alle standardmäßigen Konventionen auf alle Aktionen in ContactsConventionController angewendet:
```
[ApiController]
[ApiConventionType(typeof(DefaultApiConventions))]
[Route("api/[controller]")]
public class ContactsConventionController : ControllerBase
{
```
Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute, auf eine Assembly angewendet: Wendet den angegebenen Konventionstyp auf alle Controller in der aktuellen Assembly an. Es empfiehlt sich, Attribute auf Assemblyebene in der Startup.cs-Datei anzuwenden.

Im folgenden Beispiel werden alle standardmäßigen Konventionen auf alle Controller in der Assembly angewendet:
```
[assembly: ApiConventionType(typeof(DefaultApiConventions))]
namespace ApiConventions
{
    public class Startup
    {
```

Erstellen von Web-API-Konventionen

Wenn die Standard-API-Konventionen Ihre Anforderungen nicht erfüllen, erstellen Sie eigene Konventionen. Eine Konvention ist:

Ein statischer Typ mit Methoden.
Geeignet, Antworttypen und Benennungsanforderungen für Aktionen zu definieren.

Antworttypen

Diese Methoden werden mit den Attributen [ProducesResponseType] oder [ProducesDefaultResponseType] versehen. Beispiel:

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

Sind keine spezielleren Metadatenattribute vorhanden, erzwingt ein Anwenden dieser Konvention auf eine Assembly, dass:

Die Konventionsmethode für jede Aktion namens Find gilt.
Ein Parameter namens id in der Find-Aktion vorhanden ist.

Benennungsanforderungen

Die Attribute [ApiConventionNameMatch] und [ApiConventionTypeMatch] können auf die Konventionsmethode angewendet werden, die die Aktionen bestimmt, für die sie gelten. Beispiel:

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

Im vorherigen Beispiel:

Die auf die Methode angewendete Option Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Prefix gibt an, dass die Konvention für jede Aktion gilt, die das Präfix „Find“ hat. Beispiele für übereinstimmende Aktionen sind Find, FindPet und FindById.
Die auf den Parameter angewendete Option Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Suffix gibt an, dass die Konvention für jede Methode gilt, die genau einen Parameter hat, der mit dem Suffix „id“ endet. Beispiele sind Parameter wie id und petId. Vergleichbar kann ApiConventionTypeMatch auf Typen angewendet, um den Parametertyp einzuschränken. Ein params[]-Argument gibt verbleibende Parameter an, die nicht explizit abgeglichen werden müssen.