路由参数不同的多个HttpGet无法支持不同的SwaggerResponse

wwtsj6pe  于 2022-12-13  发布在  其他
关注(0)|答案(1)|浏览(165)

我使用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个端点的返回类型的文档输出?

bjg7j2ky

bjg7j2ky1#

看起来swagger很不高兴,因为两个端点都返回一个包含相同传输对象的类型。
例如:
PaginationResult,它具有TransferObject的列表和仅具有1个TransferObject的QueryResult。尽管类型不同,但TransferObject将导致“不能将schemaId用于类型Y,因为它已用于类型Z”。
我通过在swagger配置中添加以下行来修复这个问题

services.AddSwaggerGen(
  c =>
  {
    // Removed earlier config for simplicity
    c.CustomSchemaIds(type => type.ToString());
  });

相关问题