Bagikan melalui

Menggunakan penganalisis API web

  • Artikel

ASP.NET Core menyediakan paket penganalisis MVC yang dimaksudkan untuk digunakan dengan proyek API web. Penganalisis bekerja dengan pengontrol yang dianotasi dengan ApiControllerAttribute, sambil membangun konvensi API web.

Paket penganalisis memberi tahu Anda tentang tindakan pengontrol apa pun yang:

  • Mengembalikan kode status yang tidak dinyatakan.
  • Mengembalikan hasil keberhasilan yang tidak dinyatakan.
  • Dokumen kode status yang tidak dikembalikan.
  • Menyertakan pemeriksaan validasi model eksplisit.

Mereferensikan paket penganalisis

Penganalisis disertakan dalam .NET Core SDK. Untuk mengaktifkan penganalisis dalam proyek Anda, sertakan IncludeOpenAPIAnalyzers properti dalam file proyek:

<PropertyGroup>
 <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers>
</PropertyGroup>

Penganalisis untuk konvensi API web

Dokumen OpenAPI berisi kode status dan jenis respons yang dapat dikembalikan oleh tindakan. Dalam ASP.NET Core MVC, atribut seperti ProducesResponseTypeAttribute dan ProducesAttribute digunakan untuk mendokumen tindakan. ASP.NET dokumentasi API web Core dengan Swagger / OpenAPI masuk ke detail lebih lanjut tentang mendokumen API web Anda.

Salah satu penganalisis dalam paket memeriksa pengontrol yang diannotasikan dengan ApiControllerAttribute dan mengidentifikasi tindakan yang tidak sepenuhnya mendokumentasikan respons mereka. Pertimbangkan contoh berikut:

// GET api/contacts/{guid}
[HttpGet("{id}", Name = "GetById")]
[ProducesResponseType(typeof(Contact), StatusCodes.Status200OK)]
public IActionResult Get(string id)
{
    var contact = _contacts.Get(id);

    if (contact == null)
    {
        return NotFound();
    }

    return Ok(contact);
}

Tindakan sebelumnya mendokumen jenis pengembalian keberhasilan HTTP 200 tetapi tidak mendokumen kode status kegagalan HTTP 404. Penganalisis melaporkan dokumentasi yang hilang untuk kode status HTTP 404 sebagai peringatan. Opsi untuk memperbaiki masalah disediakan.

analyzer reporting a warning

Penganalisis memerlukan Microsoft.NET.Sdk.Web

Penganalisis tidak berfungsi dengan proyek pustaka atau proyek yang mereferensikan Sdk="Microsoft.NET.Sdk".

Sumber Daya Tambahan: