使用 Web API 慣例

發行項
11/30/2023

可以擷取一般 API 文件，並將其套用至多個動作、控制器或組件內的所有控制器。 Web API 慣例為使用 [ProducesResponseType] 裝飾個別動作的替代品。

慣例可讓您：

定義從特定動作類型傳回的最常見傳回型別和狀態碼。
識別偏離已定義標準的動作。

預設慣例可從 Microsoft.AspNetCore.Mvc.DefaultApiConventions 取得。透過將 ValuesController.cs 新增至 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)
        {
        }
    }
}

遵循 ValuesController.cs 中模式的動作將與預設慣例搭配運作。如果預設慣例不符合您的需求，請參閱建立 Web API 慣例。

在執行階段，Microsoft.AspNetCore.Mvc.ApiExplorer 了解慣例。 ApiExplorer 是 MVC 與 OpenAPI (也稱為 Swagger) 文件產生器通訊的抽象層。來自套用慣例的屬性會與動作建立關聯，且包含在動作的 OpenAPI 文件中。 API 分析器也了解慣例。若您的動作為非傳統的 (例如，其傳回未由套用慣例所記載的狀態碼)，就會出現警告，建議您記載狀態碼。

檢視或下載範例程式碼 \(英文\) (如何下載)

套用 Web API 慣例

慣例不會進行撰寫；各個動作可能僅會與一個慣例建立關聯。相較於較不特定的慣例，更特定的慣例擁有較高的優先順序。當兩個以上相同屬性的慣例套用至動作時，慣例就具有不確定性。下列選項的作用為將慣例套用至動作，其順序為從最特定到最不特定：

Microsoft.AspNetCore.Mvc.ApiConventionMethodAttribute：會套用至個別動作，並會指定慣例類型及其套用的慣例方法。

在下列範例中，預設慣例類型的 Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put 慣例方法會套用至 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();
}

Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put 慣例方法會將下列屬性套用至動作：

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

如需有關 [ProducesDefaultResponseType],的詳細資訊，請參閱預設回應 \(英文\)。

套用到控制器的 Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute：會將指定的慣例類型套用至控制器上的所有動作。慣例方法由提示所標記，且那些提示會決定要套用慣例方法的動作。如需提示的詳細資訊，請參閱建立 Web API 慣例。

在下列範例中，會將一組預設的慣例套用至 ContactsConventionController 中的所有動作：
```
[ApiController]
[ApiConventionType(typeof(DefaultApiConventions))]
[Route("api/[controller]")]
public class ContactsConventionController : ControllerBase
{
```
套用至組件的 Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute：會將指定的慣例類型套用至目前組件中的所有控制器。建議您將組件層級屬性套用至 Startup.cs 檔案。

在下列範例中，會將一組預設的慣例套用至組件中的所有控制器：
```
[assembly: ApiConventionType(typeof(DefaultApiConventions))]
namespace ApiConventions
{
    public class Startup
    {
```

建立 Web API 慣例

如果預設 API 慣例不符合您的需求，請建立您自己的慣例。慣例為：

具有方法的靜態類型。
能夠定義動作的回應類型和命名需求。

回應類型

使用 [ProducesResponseType] 或 [ProducesDefaultResponseType] 屬性標註這些方法。例如：

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

如果沒有更特定的中繼資料屬性，將此慣例套用至組件可確保：

將慣例方法套用至任何名為 Find 的動作。
Find 動作中有名為 id 的參數。

命名需求

您可以將 [ApiConventionNameMatch] 和 [ApiConventionTypeMatch] 屬性套用至會決定其套用動作的慣例方法。例如：

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

在前述範例中:

套用至方法的 Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Prefix 選項表示慣例會比對任何前置詞為 "Find" 的動作。相符動作範例包括 Find、FindPet 和 FindById。
套用至參數的 Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Suffix 表示慣例會比對只有一個以後置詞識別碼結尾之參數的方法。範例包括 id 或 petId 等參數。同樣地，ApiConventionTypeMatch 可套用至類型來限制參數類型。 params[] 引數表示其餘參數不需要明確相符。