Menggunakan konvensi API web

Artikel
11/30/2023

Dokumentasi API umum dapat diekstrak dan diterapkan ke beberapa tindakan, pengontrol, atau semua pengontrol dalam rakitan. Konvensi API Web adalah pengganti untuk menghias tindakan individual dengan [ProducesResponseType].

Konvensi memungkinkan Anda untuk:

Tentukan jenis pengembalian dan kode status yang paling umum yang dikembalikan dari jenis tindakan tertentu.
Identifikasi tindakan yang menyimpang dari standar yang ditentukan.

Konvensi default tersedia dari Microsoft.AspNetCore.Mvc.DefaultApiConventions. Konvensi ditunjukkan dengan ditambahkan ke ValuesController.cstemplat proyek API :

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

Tindakan yang mengikuti pola dalam ValuesController.cs pekerjaan dengan konvensi default. Jika konvensi default tidak memenuhi kebutuhan Anda, lihat Membuat konvensi API web.

Pada runtime, Microsoft.AspNetCore.Mvc.ApiExplorer memahami konvensi. ApiExplorer adalah abstraksi MVC untuk berkomunikasi dengan generator dokumen OpenAPI (juga dikenal sebagai Swagger). Atribut dari konvensi yang diterapkan dikaitkan dengan tindakan dan disertakan dalam dokumentasi OpenAPI tindakan. Penganalisis API juga memahami konvensi. Jika tindakan Anda tidak konvensional (misalnya, tindakan mengembalikan kode status yang tidak didokumenkan oleh konvensi yang diterapkan), peringatan mendorong Anda untuk mendokumen kode status.

Melihat atau mengunduh kode sampel (cara mengunduh)

Menerapkan konvensi API web

Konvensi tidak menyusun; setiap tindakan dapat dikaitkan dengan tepat satu konvensi. Konvensi yang lebih spesifik lebih diutamakan daripada konvensi yang kurang spesifik. Pemilihan tidak deterministik ketika dua atau beberapa konvensi dengan prioritas yang sama berlaku untuk tindakan. Opsi berikut ini ada untuk menerapkan konvensi ke tindakan, dari yang paling spesifik hingga yang paling tidak spesifik:

Microsoft.AspNetCore.Mvc.ApiConventionMethodAttribute — Berlaku untuk tindakan individual dan menentukan jenis konvensi dan metode konvensi yang berlaku.

Dalam contoh berikut, metode konvensi jenis Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put konvensi default diterapkan ke Update tindakan:

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

Metode Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put konvensi menerapkan atribut berikut ke tindakan:

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

Untuk informasi selengkapnya tentang [ProducesDefaultResponseType], lihat Respons Default.

Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute diterapkan ke pengontrol — Menerapkan jenis konvensi yang ditentukan ke semua tindakan pada pengontrol. Metode konvensi ditandai dengan petunjuk yang menentukan tindakan yang diterapkan metode konvensi. Untuk informasi selengkapnya tentang petunjuk, lihat Membuat konvensi API web).

Dalam contoh berikut, kumpulan konvensi default diterapkan ke semua tindakan di ContactsConventionController:
```
[ApiController]
[ApiConventionType(typeof(DefaultApiConventions))]
[Route("api/[controller]")]
public class ContactsConventionController : ControllerBase
{
```
Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute diterapkan ke rakitan — Menerapkan jenis konvensi yang ditentukan ke semua pengontrol di rakitan saat ini. Sebagai rekomendasi, terapkan atribut tingkat perakitan dalam Startup.cs file.

Dalam contoh berikut, kumpulan konvensi default diterapkan ke semua pengontrol di perakitan:
```
[assembly: ApiConventionType(typeof(DefaultApiConventions))]
namespace ApiConventions
{
    public class Startup
    {
```

Membuat konvensi API web

Jika konvensi API default tidak memenuhi kebutuhan Anda, buat konvensi Anda sendiri. Konvensinya adalah:

Jenis statis dengan metode.
Mampu menentukan jenis respons dan persyaratan penamaan pada tindakan.

Jenis respons

Metode ini diannotasikan dengan [ProducesResponseType] atribut atau [ProducesDefaultResponseType] . Contohnya:

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

Jika atribut metadata yang lebih spesifik tidak ada, menerapkan konvensi ini ke perakitan memberlakukan bahwa:

Metode konvensi berlaku untuk tindakan apa pun bernama Find.
Parameter bernama id ada pada Find tindakan.

Persyaratan penamaan

Atribut [ApiConventionNameMatch] dan [ApiConventionTypeMatch] dapat diterapkan ke metode konvensi yang menentukan tindakan yang diterapkan. Contohnya:

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

Dalam contoh sebelumnya:

Opsi Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Prefix yang diterapkan ke metode menunjukkan bahwa konvensi cocok dengan tindakan apa pun yang diawali dengan "Temukan". Contoh tindakan pencocokan meliputi Find, , FindPetdan FindById.
Diterapkan Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Suffix ke parameter menunjukkan bahwa konvensi cocok dengan metode dengan tepat satu parameter yang berakhiran pengidentifikasi akhiran. Contohnya termasuk parameter seperti id atau petId. ApiConventionTypeMatch juga dapat diterapkan ke jenis untuk membatasi jenis parameter. Argumen params[] menunjukkan parameter tersisa yang tidak perlu dicocokkan secara eksplisit.

Share via