Sử dụng Web API Analyzers (bộ phân tích)

ASP.NET Core cung cấp một gói MVC analyzers (bộ phân tích MVC) dành cho các dự án web API. Các analyzer làm việc với controller được chú thích bằng [ApiControllerAttribute], đồng thời dựa trên các web API conventions (quy ước web API).

Gói analyzer thông báo khi có action trong controller:

Trả về status code (mã trạng thái) chưa được khai báo.
Trả về kết quả thành công chưa được khai báo.
Tài liệu hóa một status code không thực sự được trả về.
Bao gồm kiểm tra xác thực model (model validation check) tường minh.

Tham chiếu gói analyzer

Các analyzer được tích hợp trong .NET SDK. Để kích hoạt analyzer trong dự án, thêm thuộc tính IncludeOpenAPIAnalyzers vào file project:

xml

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

Analyzer cho Web API Conventions

Tài liệu OpenAPI (OpenAPI documents) chứa status code và kiểu response mà action có thể trả về. Trong ASP.NET Core MVC, các thuộc tính (attribute) như [ProducesResponseTypeAttribute] và [ProducesAttribute] được dùng để tài liệu hóa action.

Một trong các analyzer trong gói kiểm tra controller được chú thích bằng [ApiControllerAttribute] và xác định các action không tài liệu hóa đầy đủ response của chúng. Hãy xem ví dụ sau:

csharp

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

Action trên tài liệu hóa kiểu trả về thành công HTTP 200 nhưng không tài liệu hóa status code lỗi HTTP 404. Analyzer báo cáo tài liệu thiếu cho status code HTTP 404 dưới dạng cảnh báo (warning) và cung cấp tùy chọn sửa lỗi.

!analyzer báo cáo cảnh báo

Analyzer yêu cầu Microsoft.NET.Sdk.Web

Analyzer không hoạt động với dự án thư viện (library project) hoặc dự án tham chiếu Sdk="Microsoft.NET.Sdk".