共用方式為

使用 Web API 慣例

一般 API 檔 可以擷取並套用至元件內的多個動作、控制器或所有控制器。 Web API 規範是一種替代方法，取代對個別動作進行標註 [ProducesResponseType]。

慣例可讓您：

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

默認慣例可從 Microsoft.AspNetCore.Mvc.DefaultApiConventions取得。 慣例會示範在 ValuesController.cs 專案範本中新增 ：

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的動作。
  • 名為 id 的參數會出現在動作上 Find 。

命名規範

[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[] 變數表示不需要明確比對的其餘參數。

其他資源

  • Last updated on