timothy
214fad2dcd
`api.paging-zero-based` says `pageNum` is 0-based across `/api/v1` and every wrapper of it. That was true of the MCP tool catalog and the docs, and not true of the generated OpenAPI document: all 24 paging parameters across the 12 paged operations were emitted with no `description` at all, so a consumer reading only `v1.json` — the intended contract, and what generated clients surface to their users — had to infer the base from `default: 0`. That is the same inference that cost #487 a verification pass on the MCP side, where the description was present but wrong. Annotates each `[FromQuery]` paging parameter with `[Description]` (`System.ComponentModel`), the mechanism `parentId` already used in ImagesController, and regenerates `v1.json`. `pageSize` states the endpoint's OWN cap, because the caps genuinely differ — 100 typical, 200 auto-tune members, 1000 search/all-items — and the record forbids documenting one global number; it also states that the offset derives from the effective (capped) size, so an over-large `pageSize` narrows the page instead of widening the offset. The generated TypeScript client covers DTOs only, not query parameters, so it is unchanged; `endpoint-index.md` carries summaries, not parameter descriptions, so it is unchanged too. Pinned by OpenApiPagingContractTests against the in-process generated document. The test NAMES the expected set of 12 paged operations rather than only filtering for parameters called `pageNum`: a filter cannot see an endpoint that should page and doesn't, which is exactly how two MCP tools escaped the equivalent check in #616. Set equality is asserted in both directions, and the caps are pinned per endpoint so a description naming the wrong cap fails — a wrong justification outlives a wrong line. Mutation-verified both ways: dropping one `[Description]` reddens the description test, and making one endpoint stop exposing `pageNum`/`pageSize` under those names reddens the set-equality test. Refs #633 Decisions-Edit: yes
42 lines
1.9 KiB
C#
42 lines
1.9 KiB
C#
using System.ComponentModel;
|
|
using ErsatzTV.Application.LibraryBrowse;
|
|
using ErsatzTV.Core.Api.LibraryBrowse;
|
|
using MediatR;
|
|
using Microsoft.AspNetCore.Http;
|
|
using Microsoft.AspNetCore.Mvc;
|
|
|
|
namespace ErsatzTV.Controllers.Api;
|
|
|
|
[ApiController]
|
|
public class LibraryBrowseController(IMediator mediator) : ControllerBase
|
|
{
|
|
private const int MaxPageSize = 100;
|
|
|
|
[HttpGet("/api/v1/library/browse", Name = "BrowseLibrary")]
|
|
[Tags("Libraries")]
|
|
[EndpointSummary("Browse and search library items")]
|
|
[EndpointGroupName("general")]
|
|
[ProducesResponseType(typeof(PagedLibraryBrowseItemsResponseModel), StatusCodes.Status200OK)]
|
|
public async Task<PagedLibraryBrowseItemsResponseModel> Browse(
|
|
[FromQuery] string query = "",
|
|
[FromQuery] int? libraryId = null,
|
|
[FromQuery] LibraryBrowseMediaType? mediaType = null,
|
|
[FromQuery]
|
|
[Description("0-based page index: the first page is 0, not 1. A negative value is clamped to 0.")]
|
|
int pageNum = 0,
|
|
[FromQuery]
|
|
[Description("Rows per page (default 100); capped at 100 for this endpoint. The page offset is derived from the effective (capped) size, so a larger value narrows the page instead of widening the offset.")]
|
|
int pageSize = 100,
|
|
[FromQuery]
|
|
[Description("Parent id for a drill-in listing; only used with mediaType=TelevisionSeason (that show's seasons), mediaType=Episode (that season's episodes) or mediaType=MusicVideo (that artist's music videos), ignored otherwise")]
|
|
int? parentId = null,
|
|
CancellationToken cancellationToken = default)
|
|
{
|
|
int clampedPageNum = Math.Max(0, pageNum);
|
|
int clampedPageSize = Math.Clamp(pageSize, 1, MaxPageSize);
|
|
return await mediator.Send(
|
|
new GetLibraryBrowseItems(query, libraryId, mediaType, clampedPageNum, clampedPageSize, parentId),
|
|
cancellationToken);
|
|
}
|
|
}
|