通过

使用 Web API 约定

可以提取常见的 API 文档 并将其应用于程序集中的多个操作、控制器或所有控制器。 Web API 约定是替代为单独操作添加注释或属性的方式。

约定允许你：

  • 定义从特定作类型返回的最常见返回类型和状态代码。
  • 确定偏离定义标准的行动。

默认约定可从 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 约定不符合需求，请创建自己的约定。 约定为：

响应类型

这些方法被或属性标注。 例如：

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

其他资源