使用 Web API 约定

作者:Pranav KrishnamoorthyScott 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 约定

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

  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[] 参数指示无需显式匹配的剩余参数。

其他资源

上一篇:使用 Web API 分析器

下一篇:处理 ASP.NET Core Web API 中的错误

关注微信小程序
程序员编程王-随时随地学编程

扫描二维码
程序员编程王

扫一扫关注最新编程教程