无法将分页信息添加到生成的 swagger 中的响应

Question

我有一个基于 .Net 2.2 的 Web 应用程序，我正在使用 it's github page 设置的 Swashbuckle 生成它 Swagger.json。我的问题是分页信息未显示在“200”响应类型中。应该有一个分页结果列表，但它只显示结果对象，没有分页。

我尝试了基于 Swashbuckle 的 github 页面的不同配置，还尝试使用 [required] 注释来注释 PaginatedList Class' 属性。无法前进。

在 Startup.cs 我使用 Mvc 并将兼容性版本设置为 2.2:

services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2)

我有以下 Swagger 配置：

services.AddSwaggerGen(swaggerSetup =>
        {
            swaggerSetup.CustomSchemaIds(type => type.ToString());


            swaggerSetup.SwaggerDoc("v1", new OpenApiInfo()
            {
                Title = "Web App",
                Version = "v1",
                Description = "**descript**",


            });


            swaggerSetup.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
            {
                ...
            });




            var xmlFile = $"...";
            var xmlPath = Path.Combine(BaseDirectory, xmlFile);
            swaggerSetup.IncludeXmlComments(xmlPath);


            swaggerSetup.AddFluentValidationRules();


            swaggerSetup.DocumentFilter<UserIdFilter>();
            swaggerSetup.OperationFilter<JWTAuthOperationAttribute>();
        });

我的控制器：

    [HttpGet("findAllItemsByStatus/{status}")]
    [Authorize]
    [Consumes("application/json")]
    [Produces("application/json")]
    [ProducesResponseType(typeof(GetListItemsResult), StatusCodes.Status200OK)]
    [ProducesResponseType(typeof(Errors), StatusCodes.Status403Forbidden)]
    public async Task<IActionResult> getList([FromQuery] GetListItems request, string status)
    {
        request.UserId = _securityTokenProvider.GetAuthenticatedUserID(HttpContext);
        request.ItemType = status;


        return Ok(await _mediator.Send(request));
    }

GetListItems class 定义：

public class GetListItems : IRequest<PaginatedList<ItemDTO, GetListItemsResult>>
    {
        public Guid UserId { get; set; }
        public string ItemType { get; set; } = "active";
        public int Page { get; set; } = 1;
        public int PerPage { get; set; } = 10;
    }

处理程序class定义：

public class GetListItemsHandler : UserAuthBasedQuery<GetListItems, PaginatedList<ItemDTO, GetListItemsResult>>

它的句柄方法具有以下签名：

public override async Task<PaginatedList<ItemDTO, GetListItemsResult>> Handle(GetListItems request, CancellationToken cancellationToken)

分页列表Class:

public class PaginatedList<T, TOut> where T : class
{
    public int Page { get; set; }
    public int PerPage { get; set; }
    public int Total { get; set; }
    public IEnumerable<TOut> Data { get; set; }


    public static async Task<PaginatedList<T, TOut>> FromIQueryableAsync(IQueryable<T> query, int page, int perPage, Func<T, TOut> formatterCallback) {
        var thisPage = await query
            .Skip((page - 1) * perPage)
            .Take(perPage)
            .ToListAsync();
        
        var total = await query.CountAsync();


        return new PaginatedList<T, TOut>{
            Page = page,
            PerPage = perPage,
            Total = total,
            Data = thisPage.Select(i => formatterCallback(i))
        };
    }        
}

生成的 Swagger，其中状态代码 200 的响应不是分页列表而是结果对象本身：

'/api/v1/Item/findAllItemsByStatus/{status}':
    get:
      tags:
        - Item
      summary: Lists all Items by status
      description:
        The status can be:
        active
        inactive
        expired 
      operationId: Item_getList
      parameters:
        - name: userId
          in: query
          schema:
            type: string
            format: guid
          nullable: false
        - name: ItemType
          in: query
          schema:
            type: string
          nullable: false
        - name: page
          in: query
          schema:
            type: integer
            format: int32
          nullable: false
        - name: perPage
          in: query
          schema:
            type: integer
            format: int32
          nullable: false
        - name: status
          in: path
          required: true
          schema:
            type: string
          x-position: 1
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetListItemsResult'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'

Answer 1

好的，我找到了解决方案：

[ProducesResponseType(typeof(PaginatedList<ItemDTO, GetListItemsResult>), StatusCodes.Status200OK)]
PaginatedList<AuctionDTO, GetListAuctionsResult>
    [ProducesResponseType(typeof(Errors), StatusCodes.Status403Forbidden)]
    public async Task<IActionResult> getList([FromQuery] GetListItems request, string status)
    {
...
}

我必须在响应类型中使用类型“PaginatedList”。我在想 Swashbuckle 会正确地选择内部类型 （处理程序的 return 类型） 但我错了，我必须指定确切的类型（分页列表在我的例子中）在控制器的注释中。

无法将分页信息添加到生成的 swagger 中的响应

Cannot add pagination info to response in the generated swagger

.net-core

pagination

swagger

swashbuckle.aspnetcore