Freigeben über

Verwenden von Web-API-Konventionen

Allgemeine API-Dokumentation kann extrahiert und auf mehrere Aktionen, Controller oder alle Controller innerhalb einer Assembly angewendet werden. Web-API-Konventionen sind ein Ersatz für die Dekoration einzelner Aktionen mit [ProducesResponseType].

Eine Konvention ermöglicht Folgendes:

  • Definieren Sie die gängigsten Rückgabetypen und Statuscodes, die von einem bestimmten Aktionstyp zurückgegeben werden.
  • Identifizieren Sie Aktionen, die vom definierten Standard abweichen.

Standardkonventionen sind verfügbar von Microsoft.AspNetCore.Mvc.DefaultApiConventions. Die Konventionen werden veranschaulicht, indem ValuesController.cs zu einer API-Projektvorlage hinzugefügt wird.

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 in ValuesController.cs folgen, arbeiten mit den Standardkonventionen. Wenn die Standardkonventionen Ihre Anforderungen nicht erfüllen, lesen Sie "Erstellen von Web-API-Konventionen".

Zur Laufzeit versteht Microsoft.AspNetCore.Mvc.ApiExplorer Konventionen. ApiExplorer ist die MVC-Abstraktion für die Kommunikation mit OpenAPI (auch als Swagger bekannt) Dokumentengeneratoren. Attribute aus der angewendeten Konvention sind einer Aktion zugeordnet und in der OpenAPI-Dokumentation der Aktion enthalten. API-Analysegeräte verstehen auch Konventionen . Wenn Ihre Aktion unkonventionell ist (z. B. gibt sie einen Statuscode zurück, der nicht von der angewendeten Konvention dokumentiert ist), empfiehlt eine Warnung, den Statuscode zu dokumentieren.

Anzeigen oder Herunterladen von Beispielcode (Anleitung zum Herunterladen)

Anwenden von Web-API-Konventionen

Konventionen bringen keine Komposition hervor; jede Aktion kann genau einer Konvention zugeordnet sein. Spezifischere Konventionen haben Vorrang vor weniger spezifischen Konventionen. Die Auswahl ist nicht deterministisch, wenn zwei oder mehr Konventionen derselben Priorität auf eine Aktion angewendet werden. Die folgenden Optionen sind vorhanden, um eine Konvention auf eine Aktion anzuwenden, von der spezifischsten auf die am wenigsten spezifische:

  1. Microsoft.AspNetCore.Mvc.ApiConventionMethodAttribute — Gilt für einzelne Aktionen und gibt den Konventionstyp und die angewendete Konventionsmethode an.

    Im folgenden Beispiel wird die Konventionsmethode des Standardkonventionstyps Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put 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 [ProducesDefaultResponseType]finden Sie unter "Standardantwort".

  2. Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute auf einen Controller angewendet – Wendet den angegebenen Konventionstyp auf alle Aktionen auf dem Controller an. Eine Konventionsmethode ist mit Hinweisen gekennzeichnet, die die Aktionen bestimmen, auf die die Konventionsmethode angewendet wird. Weitere Informationen zu Hinweisen finden Sie unter Erstellen von Web-API-Konventionen).

    Im folgenden Beispiel wird der Standardsatz von Konventionen auf alle Aktionen in ContactsConventionController angewendet:

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

  3. Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute auf eine Assembly angewendet – Wendet den angegebenen Konventionstyp auf alle Controller in der aktuellen Assembly an. Wenden Sie als Empfehlung Attribute auf Assemblyebene in der Startup.cs Datei an.

    Im folgenden Beispiel wird der Standardsatz von 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:

Antworttypen

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

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

Wenn spezifischere Metadatenattribute nicht vorhanden sind, erzwingt das Anwenden dieser Konvention auf eine Assembly folgendes:

  • Die Konventionsmethode gilt für jede Aktion mit dem Namen Find.
  • Ein benannter id Parameter ist für die Find Aktion vorhanden.

Benennungsanforderungen

Die [ApiConventionNameMatch] Und [ApiConventionTypeMatch] Attribute können auf die Konventionsmethode angewendet werden, die die Aktionen bestimmt, auf die sie angewendet werden. Beispiel:

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

Im vorherigen Beispiel:

  • Die Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Prefix auf die Methode angewendete Option gibt an, dass die Konvention mit einer Aktion übereinstimmt, die mit dem Präfix "Suchen" versehen ist. Beispiele für übereinstimmende Aktionen sind Find, FindPet und FindById.
  • Die Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Suffix anwendung auf den Parameter gibt an, dass die Konvention Methoden mit genau einem Parameter abgleicht, der auf dem Suffixbezeichner endet. Beispiele sind Parameter wie id z. B. oder petId. ApiConventionTypeMatch kann ähnlich auf Datentypen verwendet werden, um den Parametertyp einzuschränken. Ein params[] Argument gibt verbleibende Parameter an, die nicht explizit übereinstimmen müssen.

Weitere Ressourcen

  • Last updated on