Web API 约定
默认的约定
集将应用于 ContactsConventionController 中的所有操作:
[ApiController]
[ApiConventionType(typeof(DefaultApiConventions))]
[Route("api/[controller]")]
public class ContactsConventionController : ControllerBase
{
默认的约定集将应用于程序集中的所有操作:
[assembly: ApiConventionType(typeof(DefaultApiConventions))]
namespace ApiConventions
{
public class Startup
{
创建 Web API 约定
如果默认 API 约定不能满足需要,请创建自己的约定。 约定是:
响应类型
这些方法使用 [ProducesResponseType]
或 [ProducesDefaultResponseType]
属性进行批注。 例如:
C#复制
public static class MyAppConventions
{
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public static void Find(int id)
{
}
}
如果没有更具体的元数据属性,则将此约定应用于程序集可强制实现以下内容:
- 该约定方法应用于所有名为
Find
的操作。 -
id
操作上存在名为Find
的参数。
命名要求
[ApiConventionNameMatch]
和 [ApiConventionTypeMatch]
属性可应用于约定方法,确定它们所要应用的操作。 例如:
C#复制
[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[]
参数指示无需显式匹配的剩余参数。