使用 Web API 约定Use web API conventions

本文内容

作者：Pranav Krishnamoorthy 和 Scott Addie

ASP.NET Core 2.2 及更高版本附带一种方法，可提取常见的 API 文档并将其应用于多个操作、控制器或某程序集内的所有控制器。Web API 约定可替代使用 [ProducesResponseType] 来装饰单个操作。

使用此约定，可以：

  • 定义通过特定操作类型返回的、最常见的返回类型和状态代码。
  • 识别偏离所定义的标准的操作。

ASP.NET Core MVC 2.2 及更高版本在 Microsoft.AspNetCore.Mvc.DefaultApiConventions 中包含一组默认的约定。约定基于 ASP.NET Core API 项目模板中提供的控件 (ValuesController.cs)。若操作遵循模板中的模式，则应成功使用默认约定。如果默认约定不能满足需要，请参阅创建 Web API 约定。

在运行时，Microsoft.AspNetCore.Mvc.ApiExplorer 会了解约定。ApiExplorer 是 MVC 与 OpenAPI（也称为 Swagger）文档生成器进行通信的抽象内容。已应用的约定中的属性与某个操作相关联，并包含在操作的 OpenAPI 文档中。API 分析器也会了解约定。若操作为非常规操作（例如，它返回已应用的约定未记录的状态代码），则会生成警告，建议记录该状态代码。

查看或下载示例代码（如何下载）

应用 Web API 约定Apply web API conventions

约定不是组合而成的，每个操作可能只与一个约定相关联。更明确的约定优先于不太明确的约定。当具有相同优先级的两个或更多约定应用于某个操作时，选择是不确定的。存在以下可将约定应用于操作的选项，明确性依次降低：

  • Microsoft.AspNetCore.Mvc.ApiConventionMethodAttribute — 适用于单个操作并指定应用的约定类型和约定方法。

在以下示例中，默认约定类型的 Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put 约定方法将应用于 Update 操作：

  1. // PUT api/contactsconvention/{guid}
  2. [HttpPut("{id}")]
  3. [ApiConventionMethod(typeof(DefaultApiConventions), 
  4.                      nameof(DefaultApiConventions.Put))]
  5. public IActionResult Update(string id, Contact contact)
  6. {
  7.     var contactToUpdate = _contacts.Get(id);
  9.     if (contactToUpdate == null)
  10.     {
  11.         return NotFound();
  12.     }
  14.     _contacts.Update(contact);
  16.     return NoContent();
  17. }

Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put 约定方法可将以下属性应用于操作：

  1. [ProducesDefaultResponseType]
  2. [ProducesResponseType(StatusCodes.Status204NoContent)]
  3. [ProducesResponseType(StatusCodes.Status404NotFound)]
  4. [ProducesResponseType(StatusCodes.Status400BadRequest)]

若要详细了解 [ProducesDefaultResponseType]，请参阅默认响应。

  • Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute 应用于控制器 — 将指定约定类型应用于控制器上的所有操作。约定方法都标记有提示，可确定要向其应用约定方法的操作。有关提示的详细信息，请参阅创建 Web API 约定）。

在以下示例中，默认的约定集将应用于 ContactsConventionController 中的所有操作：

  1. [ApiController]
  2. [ApiConventionType(typeof(DefaultApiConventions))]
  3. [Route("api/[controller]")]
  4. public class ContactsConventionController : ControllerBase
  5. {
  • Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute 应用于程序集 — 将指定约定类型应用于当前程序集中的所有控制器。建议将程序集级别的属性应用于 Startup.cs 文件。

在以下示例中，默认的约定集将应用于程序集中的所有操作：

  1. [assembly: ApiConventionType(typeof(DefaultApiConventions))]
  2. namespace ApiConventions
  3. {
  4.     public class Startup
  5.     {

创建 Web API 约定Create web API conventions

如果默认 API 约定不能满足需要，请创建自己的约定。约定是：

响应类型Response types

这些方法使用 [ProducesResponseType] 或 [ProducesDefaultResponseType] 属性进行批注。例如：

  1. public static class MyAppConventions
  2. {
  3.     [ProducesResponseType(StatusCodes.Status200OK)]
  4.     [ProducesResponseType(StatusCodes.Status404NotFound)]
  5.     public static void Find(int id)
  6.     {
  7.     }
  8. }

如果没有更具体的元数据属性，则将此约定应用于程序集可强制实现以下内容：

  • 该约定方法应用于所有名为 Find 的操作。
  • id 操作上存在名为 Find 的参数。

命名要求Naming requirements

[ApiConventionNameMatch] 和 [ApiConventionTypeMatch] 属性可应用于约定方法，确定它们所要应用的操作。例如：

  1. [ProducesResponseType(StatusCodes.Status200OK)]
  2. [ProducesResponseType(StatusCodes.Status404NotFound)]
  3. [ApiConventionNameMatch(ApiConventionNameMatchBehavior.Prefix)]
  4. public static void Find(
  5.     [ApiConventionNameMatch(ApiConventionNameMatchBehavior.Suffix)]
  6.     int id)
  7. { }

在上面的示例中：

  • 应用于该方法的 Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Prefix 选项表示该约定可匹配前缀是“Find”的任何操作。匹配的操作可以是 Find、FindPet 和 FindById。
  • 应用于该参数的 Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Suffix 表示该约定可匹配带有唯一以标识符作为后缀结尾的参数的方法。示例包括 id 或 petId 等参数。与此类似，可将 ApiConventionTypeMatch 应用于类型，以约束参数类型。params[] 参数指示无需显式匹配的剩余参数。

其他资源Additional resources