Megosztás a következőn keresztül:

Webes API-konvenciók használata

A közös API-dokumentáció több műveletre, vezérlőre vagy egy szerelvényen belüli összes vezérlőre is kinyerhető és alkalmazható. A webes API-konvenciók helyettesítik az egyes műveletek dekorálását.[ProducesResponseType]

A konvenciók lehetővé teszik, hogy:

  • Adja meg az adott művelettípusból visszaadott leggyakoribb visszatérési típusokat és állapotkódokat.
  • Azonosítsa a definiált szabványtól eltérő műveleteket.

Az alapértelmezett konvenciók a következőből Microsoft.AspNetCore.Mvc.DefaultApiConventionsérhetők el: . A konvenciókat az ValuesController.csAPI-projektsablonhoz hozzáadott konvenciók szemléltetik:

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

Az alapértelmezett konvenciókkal együttműködő ValuesController.cs mintákat követő műveletek. Ha az alapértelmezett konvenciók nem felelnek meg az igényeinek, tekintse meg a webes API-konvenciók létrehozását.

Futásidőben Microsoft.AspNetCore.Mvc.ApiExplorer tisztában van a konvenciókkal. ApiExplorer az MVC absztrakciója az OpenAPI (más néven Swagger) dokumentumgenerátorokkal való kommunikációhoz. Az alkalmazott konvenció attribútumai egy művelethez vannak társítva, és szerepelnek a művelet OpenAPI-dokumentációjában. Az API-elemzők a konvenciókat is megértik. Ha a művelet nem hagyományos (például olyan állapotkódot ad vissza, amelyet az alkalmazott konvenció nem dokumentál), egy figyelmeztetés arra ösztönzi, hogy dokumentálja az állapotkódot.

Mintakód megtekintése vagy letöltése (hogyan töltsd le)

Webes API-konvenciók alkalmazása

A konvenciók nem komponálnak; minden művelet pontosan egy konvencióval társítható. A konkrétabb konvenciók elsőbbséget élveznek a kevésbé specifikus konvenciókéval szemben. A kijelölés nem determinisztikus, ha egy műveletre két vagy több azonos prioritású konvenció vonatkozik. A következő lehetőségek léteznek egy művelet konvenciójának alkalmazására, a legspecifikusabbtól a legkevésbé specifikusig:

  1. Microsoft.AspNetCore.Mvc.ApiConventionMethodAttribute — Az egyes műveletekre vonatkozik, és meghatározza a konvenció típusát és az alkalmazandó konvenciós módszert.

    Az alábbi példában az alapértelmezett konvenciótípus konvenciómetódus-metódusa Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put lesz alkalmazva a Update műveletre:

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

    A Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put konvenciómetódus a következő attribútumokat alkalmazza a műveletre:

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

    További információ: [ProducesDefaultResponseType]Alapértelmezett válasz.

  2. Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute vezérlőre alkalmazva – A megadott konvenciótípust alkalmazza a vezérlőn található összes műveletre. A konvenciómetódusok olyan tippekkel vannak megjelölve, amelyek meghatározzák azokat a műveleteket, amelyekre a konvenciómetódus vonatkozik. További információ a tippekről: Webes API-konvenciók létrehozása).

    Az alábbi példában a rendszer az alapértelmezett konvenciók készletét alkalmazza a ContactsConventionController összes műveletére:

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

  3. Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute szerelvényre alkalmazva – A megadott konvenciótípust alkalmazza az aktuális szerelvény összes vezérlőjének. Javaslatként alkalmazzon szerelvényszintű attribútumokat a Startup.cs fájlban.

    Az alábbi példában a rendszer az alapértelmezett konvenciók készletét alkalmazza a szerelvény összes vezérlője esetében:

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

Webes API-konvenciók létrehozása

Ha az alapértelmezett API-konvenciók nem felelnek meg az igényeinek, hozzon létre saját konvenciókat. A konvenciók a következőek:

Választípusok

Ezek a metódusok széljegyzetekkel vagy [ProducesResponseType] attribútumokkal vannak eljegyzve[ProducesDefaultResponseType]. Például:

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

Ha konkrétabb metaadat-attribútumok hiányoznak, a konvenció szerelvényre való alkalmazása a következőt kényszeríti ki:

  • A konvenciómetódus a nevesített Findműveletekre vonatkozik.
  • A id műveleten van egy Find nevű paraméter.

Elnevezési követelmények

Az [ApiConventionNameMatch] és [ApiConventionTypeMatch] az attribútumok alkalmazhatók a konvenciós módszerre, amely meghatározza azokat a műveleteket, amelyekre vonatkoznak. Például:

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

Az előző példában:

  • A Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Prefix metódusra alkalmazott beállítás azt jelzi, hogy a konvenció megfelel a "Keresés" előtagú műveleteknek. Példák az egyező műveletekre: Find, FindPetés FindById.
  • A Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Suffix paraméterre alkalmazott paraméter azt jelzi, hogy a konvenció pontosan egy, az utótagazonosítóval végződő paraméterrel egyezik meg a metódusokkal. Ilyenek például az olyan paraméterek, mint a id vagy petIda . ApiConventionTypeMatch hasonló módon alkalmazható a típusokra a paramétertípus korlátozásához. Az params[] argumentumok olyan fennmaradó paramétereket jelölnek, amelyeket nem kell explicit módon egyeztetni.

További erőforrások

  • Last updated on