Nguon: Microsoft Learn · .NET 8.0

Sử dụng các quy ước (conventions) trong Web API

Nguồn: Use web API conventions

Tài liệu API (API documentation) chung có thể được trích xuất và áp dụng cho nhiều action, controller, hoặc tất cả controller trong một assembly. Các quy ước (conventions) trong Web API là một sự thay thế cho việc trang trí từng action riêng lẻ với [ProducesResponseType].

Một convention cho phép bạn:

Các convention mặc định có sẵn từ Microsoft.AspNetCore.Mvc.DefaultApiConventions. Các convention này được minh họa với ValuesController.cs được thêm vào template dự án API:

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

Các action tuân theo các mẫu trong ValuesController.cs hoạt động với các convention mặc định. Nếu các convention mặc định không đáp ứng nhu cầu của bạn, hãy xem phần Tạo conventions Web API.

Tại runtime, Microsoft.AspNetCore.Mvc.ApiExplorer hiểu các convention. ApiExplorer là abstraction (lớp trừu tượng) của MVC để giao tiếp với các trình tạo tài liệu OpenAPI (còn được gọi là Swagger). Các attribute từ convention được áp dụng được liên kết với một action và được đưa vào tài liệu OpenAPI của action đó. API analyzers cũng hiểu các convention. Nếu action của bạn không theo convention (ví dụ: nó trả về một mã trạng thái không được ghi lại bởi convention đã áp dụng), một cảnh báo sẽ khuyến khích bạn ghi lại mã trạng thái đó.

Áp dụng các convention Web API

Các convention không kết hợp được với nhau; mỗi action chỉ có thể được liên kết với đúng một convention. Các convention cụ thể hơn sẽ được ưu tiên hơn các convention ít cụ thể hơn. Việc lựa chọn không có tính xác định khi hai hay nhiều convention có cùng mức độ ưu tiên áp dụng cho một action. Các tùy chọn sau đây để áp dụng convention cho một action, từ cụ thể nhất đến ít cụ thể nhất:

  1. Microsoft.AspNetCore.Mvc.ApiConventionMethodAttribute — Áp dụng cho từng action riêng lẻ và chỉ định loại convention và phương thức convention áp dụng.

Trong ví dụ sau, phương thức convention Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put của loại convention mặc định được áp dụng cho action Update:

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

Phương thức convention Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put áp dụng các attribute sau cho action:

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

  1. Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute áp dụng cho controller — Áp dụng loại convention đã chỉ định cho tất cả action trong controller. Một phương thức convention được đánh dấu bằng các gợi ý (hints) xác định action mà phương thức convention áp dụng.

Trong ví dụ sau, tập convention mặc định được áp dụng cho tất cả action trong ContactsConventionController:

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

  1. Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute áp dụng cho assembly — Áp dụng loại convention đã chỉ định cho tất cả controller trong assembly hiện tại. Khuyến nghị áp dụng các attribute cấp assembly trong file Startup.cs.

Trong ví dụ sau, tập convention mặc định được áp dụng cho tất cả controller trong assembly:

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

Tạo các convention Web API

Nếu các convention API mặc định không đáp ứng nhu cầu của bạn, hãy tạo convention riêng. Một convention là:

Kiểu phản hồi (Response types)

Các phương thức này được chú thích bằng các attribute [ProducesResponseType] hoặc [ProducesDefaultResponseType]. Ví dụ:

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

Nếu không có các attribute metadata cụ thể hơn, việc áp dụng convention này cho một assembly sẽ đảm bảo rằng:

Yêu cầu đặt tên (Naming requirements)

Các attribute [ApiConventionNameMatch] và [ApiConventionTypeMatch] có thể được áp dụng cho phương thức convention để xác định action mà chúng áp dụng. Ví dụ:

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

Trong ví dụ trên: