你知道 ASP.NET Core约定吗

使用约定修饰各操作

可以提取常见 API 文档 并将其应用于程序集中的多个操作、控制器或所有控制器。 Web API 约定可替代使用 [ProducesResponseType] 来装饰单个操作。

使用此约定，可以：

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

优点

避免了为每个返回状态都添加ProducesResponseType的繁琐

Controller使用约定

注意ContactsConventionController的[ApiConventionType(typeof(DefaultApiConventions))]特性

    [ApiController]
    [ApiConventionType(typeof(DefaultApiConventions))]
    [Route("api/[controller]")]
    public class ContactsConventionController : ControllerBase

方法上约定

 #region snippet_ApiConventionMethod
        // 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();
        }
        #endregion

效果

自动 补全了200 404 400 状态下的返回值再也不用手动，为每个状态添加ProducesResponseType特性了

examples

https://github.com/huzuohuyou/DotNet6-Examples/tree/main/WebAPIConventions

参考：
https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-nswag?view=aspnetcore-6.0&tabs=visual-studio
https://docs.microsoft.com/zh-cn/aspnet/core/web-api/advanced/conventions?view=aspnetcore-6.0#create-web-api-conventions
https://docs.microsoft.com/zh-CN/dotnet/api/microsoft.aspnetcore.mvc.defaultapiconventions.create?view=aspnetcore-6.0#microsoft-aspnetcore-mvc-defaultapiconventions-create(system-object)