ASP.NET Core Web API：为返回CreatedAtRouteResult的方法添加Swagger属性

你的代码里存在两个关键问题需要修正，才能让Swagger生成准确的API文档：

1. 修正SwaggerResponse的类型参数 #

CreatedAtRouteResult是ASP.NET Core的一个包装类，它的作用是返回201状态码、资源路由URL和实际的资源数据。Swagger需要知道的是它包装的实际数据类型（也就是你的Subscription实体），而不是CreatedAtRouteResult本身。

另外你原来的代码里，400状态码对应NotFoundResult是错误的——400代表BadRequest，而NotFound对应的是404状态码，这个错误会导致Swagger文档的状态码对应关系混乱，必须修正。

2. 可选但推荐：配合ProducesResponseType属性 #

ASP.NET Core的[ProducesResponseType]属性会被ApiExplorer识别，Swashbuckle（Swagger的.NET实现）会基于它生成更准确的响应元数据，和[SwaggerResponse]配合使用效果更好。

3. 确保路由名称存在 #

你在CreatedAtRoute中使用的"GetSubscription"路由名称，必须在你的控制器中存在对应的Get方法路由，比如：

[HttpGet("{id}", Name = "GetSubscription")]
public async Task<IActionResult> GetSubscription(int id)
{
    // 实现逻辑
}

这样Swagger才能正确生成指向该资源的链接。

修改后的完整代码示例 #

using Microsoft.AspNetCore.Mvc;
using Swashbuckle.AspNetCore.Annotations;

[HttpPost]
[SwaggerOperation(Summary = "创建新订阅", Description = "根据传入的订阅DTO创建订阅，成功后返回订阅详情及资源访问URL")]
[SwaggerResponse(400, Description = "请求数据无效，比如DTO验证失败")]
[SwaggerResponse(404, Description = "关联的发行方不存在")]
[SwaggerResponse(201, typeof(Subscription), Description = "订阅创建成功，返回创建的订阅实体")]
[ProducesResponseType(typeof(Subscription), StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public async Task<IActionResult> Create([FromBody] SubscriptionDTO dto)
{
    var issuedTo = (await _tokenService.Get()).IssuedTo;
    Subscription result = await _subscriptionService.CreateAsync(dto, issuedTo.Id);
    
    return result == null ? NotFound() : CreatedAtRoute("GetSubscription", new { id = result.Id }, result);
}

额外说明 #

如果你的Swashbuckle版本是5.x及以上，还可以通过配置让Swagger自动识别ActionResult的泛型类型，但显式添加SwaggerResponse和ProducesResponseType能让文档更清晰，也避免自动识别可能出现的问题。

内容的提问来源于stack exchange，提问作者Sammani Palansuriya