Bagikan melalui

Menggunakan konvensi API web

Dokumentasi API umum dapat diekstrak dan diterapkan pada beberapa tindakan, pengontrol, atau semua pengontrol dalam sebuah 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 dijelaskan dengan menambahkan ValuesController.cs ke templat 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 berfungsi sesuai 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:

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

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

    // 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 Bawaan.

  2. 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
{

  3. 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 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 rakitan memastikan 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.
  • Aplikasi Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Suffix pada parameter menunjukkan bahwa konvensi cocok dengan metode dengan tepat satu parameter yang diakhiri dengan sufiks pengidentifikasi. 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.

Sumber daya tambahan

  • Last updated on