使用 Web API 慣例

通用 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 慣例

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

  1. 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],的詳細資訊,請參閱預設回應 \(英文\)。

  2. Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute 套用至控制器 — 將指定的慣例類型套用至控制器上的所有動作。 慣例方法會以提示標示,以決定套用慣例方法的動作。 如需提示的詳細資訊,請參閱建立 Web API 慣例

    在下列範例中,會將一組預設的慣例套用至 ContactsConventionController 中的所有動作:

    [ApiController]
    [ApiConventionType(typeof(DefaultApiConventions))]
    [Route("api/[controller]")]
    public class ContactsConventionController : ControllerBase
    {
    
  3. 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" 的動作。 相符動作範例包括 FindFindPetFindById
  • 套用至參數的 Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Suffix 表示慣例會比對只有一個以後置詞識別碼結尾之參數的方法。 範例包括 idpetId 等參數。 同樣地,ApiConventionTypeMatch 可套用至類型來限制參數類型。 params[] 引數表示其餘參數不需要明確相符。

其他資源