我使用Swashbuckle.AspNetCore.Annotations
来增强生成的文档。我有一个简单的C#控制器,它有标准的Get、Post、Delete端点。我的问题发生在我添加了一个带有路由参数的额外HttpGet时,这应该足以区分并仍然生成昂首阔步的文档。
一切似乎都很好,直到我尝试将SwaggerResponse
修改为一个端点/entities
返回一页实体,而/entities/{id}
端点返回一个实体结果。
我修改了属性注解:
[HttpGet]
[SwaggerOperation(
Summary = "summary here",
Description = "description",
OperationId = "GetPage",
Tags = new[] { "Entity" })]
[Produces("application/json")]
[SwaggerResponse(StatusCodes.Status200OK, type: typeof(PaginationResult<EntityTransferObject>))]
[SwaggerResponse(StatusCodes.Status401Unauthorized)]
[SwaggerResponse(StatusCodes.Status400BadRequest)]
public async Task<ActionResult> GetAsync(
[FromQuery] [SwaggerParameter("The entity type", Required = true)] string entityType,
[FromQuery] [SwaggerParameter("The page number to return", Required = true)]
int page,
[FromHeader(Name = "Authorization")] [SwaggerIgnore]
string token)
{
}
[HttpGet("{id:guid}")]
[SwaggerOperation(
Summary = "summary here",
Description = "description",
OperationId = "GetEntity",
Tags = new[] { "Entity" })]
[Produces("application/json")]
[SwaggerResponse(StatusCodes.Status200OK, type: typeof(ExecuteQueryResult<EntityTransferObject>))]
[SwaggerResponse(StatusCodes.Status401Unauthorized)]
[SwaggerResponse(StatusCodes.Status400BadRequest)]
public async Task<ActionResult> GetAsync(
[FromRoute] [SwaggerParameter("The entity id", Required = true)] Guid id,
[FromHeader(Name = "Authorization")] [SwaggerIgnore]
string token)
{
}
如果我生成swagger文档,我会遇到一个错误,即加载API定义失败。如果我将swagger响应类型更改为与2 /GET方法相同,它将工作。如果我只将属性添加到一个端点,它也将工作。
如果终结点不同,它们应该支持不同的状态代码响应类型?我尝试过使用.NET Core ProducesResponseType
,结果出现了同样的问题。我还尝试过将返回类型调整为更具体的类型,例如Task<ActionResult<PaginationResult<EntityTransferObject>>>
,结果也出现了同样的问题。
是否有其他方法可以增强2个端点的返回类型的文档输出?
1条答案
按热度按时间bjg7j2ky1#
看起来swagger很不高兴,因为两个端点都返回一个包含相同传输对象的类型。
例如:
PaginationResult,它具有TransferObject的列表和仅具有1个TransferObject的QueryResult。尽管类型不同,但TransferObject将导致“不能将schemaId用于类型Y,因为它已用于类型Z”。
我通过在swagger配置中添加以下行来修复这个问题