Paging params in API docs

Closes #6003
This commit is contained in:
Mark McDowall 2023-10-09 20:37:31 -07:00 committed by GitHub
parent 9f3915d4ad
commit bfaa7291e1
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
14 changed files with 320 additions and 214 deletions

View File

@ -158,6 +158,8 @@ namespace NzbDrone.Host
{
{ apikeyQuery, Array.Empty<string>() }
});
c.DescribeAllParametersInCamelCase();
});
services

View File

@ -56,7 +56,7 @@ namespace NzbDrone.Integration.Test.ApiTests.WantedTests
var series = EnsureSeries(266189, "The Blacklist", false);
EnsureEpisodeFile(series, 1, 1, Quality.SDTV);
var result = WantedCutoffUnmet.GetPaged(0, 15, "airDateUtc", "desc", "monitored", "false");
var result = WantedCutoffUnmet.GetPaged(0, 15, "airDateUtc", "desc", "monitored", false);
result.Records.Should().NotBeEmpty();
}

View File

@ -58,7 +58,7 @@ namespace NzbDrone.Integration.Test.ApiTests.WantedTests
{
EnsureSeries(266189, "The Blacklist", false);
var result = WantedMissing.GetPaged(0, 15, "airDateUtc", "desc", "monitored", "false");
var result = WantedMissing.GetPaged(0, 15, "airDateUtc", "desc", "monitored", false);
result.Records.Should().NotBeEmpty();
}

View File

@ -102,7 +102,7 @@ namespace NzbDrone.Integration.Test.Client
return Get<List<TResource>>(request);
}
public PagingResource<TResource> GetPaged(int pageNumber, int pageSize, string sortKey, string sortDir, string filterKey = null, string filterValue = null)
public PagingResource<TResource> GetPaged(int pageNumber, int pageSize, string sortKey, string sortDir, string filterKey = null, object filterValue = null)
{
var request = BuildRequest();
request.AddParameter("page", pageNumber);
@ -113,8 +113,7 @@ namespace NzbDrone.Integration.Test.Client
if (filterKey != null && filterValue != null)
{
request.AddParameter("filterKey", filterKey);
request.AddParameter("filterValue", filterValue);
request.AddParameter(filterKey, filterValue);
}
return Get<PagingResource<TResource>>(request);

View File

@ -23,9 +23,9 @@ namespace Sonarr.Api.V3.Blocklist
[HttpGet]
[Produces("application/json")]
public PagingResource<BlocklistResource> GetBlocklist()
public PagingResource<BlocklistResource> GetBlocklist([FromQuery] PagingRequestResource paging)
{
var pagingResource = Request.ReadPagingResourceFromRequest<BlocklistResource>();
var pagingResource = new PagingResource<BlocklistResource>(paging);
var pagingSpec = pagingResource.MapToPagingSpec<BlocklistResource, NzbDrone.Core.Blocklisting.Blocklist>("date", SortDirection.Descending);
return pagingSpec.ApplyToPage(_blocklistService.Paged, model => BlocklistResourceMapper.MapToResource(model, _formatCalculator));

View File

@ -2,6 +2,7 @@ using System;
using System.Collections.Generic;
using System.Linq;
using Microsoft.AspNetCore.Mvc;
using NzbDrone.Common.Extensions;
using NzbDrone.Core.CustomFormats;
using NzbDrone.Core.Datastore;
using NzbDrone.Core.DecisionEngine.Specifications;
@ -61,30 +62,24 @@ namespace Sonarr.Api.V3.History
[HttpGet]
[Produces("application/json")]
public PagingResource<HistoryResource> GetHistory(bool includeSeries, bool includeEpisode)
public PagingResource<HistoryResource> GetHistory([FromQuery] PagingRequestResource paging, bool includeSeries, bool includeEpisode, int? eventType, int? episodeId, string downloadId)
{
var pagingResource = Request.ReadPagingResourceFromRequest<HistoryResource>();
var pagingResource = new PagingResource<HistoryResource>(paging);
var pagingSpec = pagingResource.MapToPagingSpec<HistoryResource, EpisodeHistory>("date", SortDirection.Descending);
var eventTypeFilter = pagingResource.Filters.FirstOrDefault(f => f.Key == "eventType");
var episodeIdFilter = pagingResource.Filters.FirstOrDefault(f => f.Key == "episodeId");
var downloadIdFilter = pagingResource.Filters.FirstOrDefault(f => f.Key == "downloadId");
if (eventTypeFilter != null)
if (eventType.HasValue)
{
var filterValue = (EpisodeHistoryEventType)Convert.ToInt32(eventTypeFilter.Value);
var filterValue = (EpisodeHistoryEventType)eventType.Value;
pagingSpec.FilterExpressions.Add(v => v.EventType == filterValue);
}
if (episodeIdFilter != null)
if (episodeId.HasValue)
{
var episodeId = Convert.ToInt32(episodeIdFilter.Value);
pagingSpec.FilterExpressions.Add(h => h.EpisodeId == episodeId);
}
if (downloadIdFilter != null)
if (downloadId.IsNotNullOrWhiteSpace())
{
var downloadId = downloadIdFilter.Value;
pagingSpec.FilterExpressions.Add(h => h.DownloadId == downloadId);
}

View File

@ -1,5 +1,5 @@
using System.Linq;
using Microsoft.AspNetCore.Mvc;
using NzbDrone.Common.Extensions;
using NzbDrone.Core.Instrumentation;
using Sonarr.Http;
using Sonarr.Http.Extensions;
@ -18,9 +18,9 @@ namespace Sonarr.Api.V3.Logs
[HttpGet]
[Produces("application/json")]
public PagingResource<LogResource> GetLogs()
public PagingResource<LogResource> GetLogs([FromQuery] PagingRequestResource paging, string level)
{
var pagingResource = Request.ReadPagingResourceFromRequest<LogResource>();
var pagingResource = new PagingResource<LogResource>(paging);
var pageSpec = pagingResource.MapToPagingSpec<LogResource, Log>();
if (pageSpec.SortKey == "time")
@ -28,11 +28,9 @@ namespace Sonarr.Api.V3.Logs
pageSpec.SortKey = "id";
}
var levelFilter = pagingResource.Filters.FirstOrDefault(f => f.Key == "level");
if (levelFilter != null)
if (level.IsNotNullOrWhiteSpace())
{
switch (levelFilter.Value)
switch (level)
{
case "fatal":
pageSpec.FilterExpressions.Add(h => h.Level == "Fatal");

View File

@ -135,9 +135,9 @@ namespace Sonarr.Api.V3.Queue
[HttpGet]
[Produces("application/json")]
public PagingResource<QueueResource> GetQueue(bool includeUnknownSeriesItems = false, bool includeSeries = false, bool includeEpisode = false)
public PagingResource<QueueResource> GetQueue([FromQuery] PagingRequestResource paging, bool includeUnknownSeriesItems = false, bool includeSeries = false, bool includeEpisode = false)
{
var pagingResource = Request.ReadPagingResourceFromRequest<QueueResource>();
var pagingResource = new PagingResource<QueueResource>(paging);
var pagingSpec = pagingResource.MapToPagingSpec<QueueResource, NzbDrone.Core.Queue.Queue>("timeleft", SortDirection.Ascending);
return pagingSpec.ApplyToPage((spec) => GetQueue(spec, includeUnknownSeriesItems), (q) => MapToResource(q, includeSeries, includeEpisode));

View File

@ -1,4 +1,3 @@
using System.Linq;
using Microsoft.AspNetCore.Mvc;
using NzbDrone.Core.CustomFormats;
using NzbDrone.Core.Datastore;
@ -29,9 +28,9 @@ namespace Sonarr.Api.V3.Wanted
[HttpGet]
[Produces("application/json")]
public PagingResource<EpisodeResource> GetCutoffUnmetEpisodes(bool includeSeries = false, bool includeEpisodeFile = false, bool includeImages = false)
public PagingResource<EpisodeResource> GetCutoffUnmetEpisodes([FromQuery] PagingRequestResource paging, bool includeSeries = false, bool includeEpisodeFile = false, bool includeImages = false, bool monitored = true)
{
var pagingResource = Request.ReadPagingResourceFromRequest<EpisodeResource>();
var pagingResource = new PagingResource<EpisodeResource>(paging);
var pagingSpec = new PagingSpec<Episode>
{
Page = pagingResource.Page,
@ -40,16 +39,7 @@ namespace Sonarr.Api.V3.Wanted
SortDirection = pagingResource.SortDirection
};
var filter = pagingResource.Filters.FirstOrDefault(f => f.Key == "monitored");
if (filter != null && filter.Value == "false")
{
pagingSpec.FilterExpressions.Add(v => v.Monitored == false || v.Series.Monitored == false);
}
else
{
pagingSpec.FilterExpressions.Add(v => v.Monitored == true && v.Series.Monitored == true);
}
pagingSpec.FilterExpressions.Add(v => v.Monitored == monitored || v.Series.Monitored == monitored);
var resource = pagingSpec.ApplyToPage(_episodeCutoffService.EpisodesWhereCutoffUnmet, v => MapToResource(v, includeSeries, includeEpisodeFile, includeImages));

View File

@ -1,4 +1,3 @@
using System.Linq;
using Microsoft.AspNetCore.Mvc;
using NzbDrone.Core.CustomFormats;
using NzbDrone.Core.Datastore;
@ -25,9 +24,9 @@ namespace Sonarr.Api.V3.Wanted
[HttpGet]
[Produces("application/json")]
public PagingResource<EpisodeResource> GetMissingEpisodes(bool includeSeries = false, bool includeImages = false)
public PagingResource<EpisodeResource> GetMissingEpisodes([FromQuery] PagingRequestResource paging, bool includeSeries = false, bool includeImages = false, bool monitored = true)
{
var pagingResource = Request.ReadPagingResourceFromRequest<EpisodeResource>();
var pagingResource = new PagingResource<EpisodeResource>(paging);
var pagingSpec = new PagingSpec<Episode>
{
Page = pagingResource.Page,
@ -36,16 +35,7 @@ namespace Sonarr.Api.V3.Wanted
SortDirection = pagingResource.SortDirection
};
var monitoredFilter = pagingResource.Filters.FirstOrDefault(f => f.Key == "monitored");
if (monitoredFilter != null && monitoredFilter.Value == "false")
{
pagingSpec.FilterExpressions.Add(v => v.Monitored == false || v.Series.Monitored == false);
}
else
{
pagingSpec.FilterExpressions.Add(v => v.Monitored == true && v.Series.Monitored == true);
}
pagingSpec.FilterExpressions.Add(v => v.Monitored == monitored || v.Series.Monitored == monitored);
var resource = pagingSpec.ApplyToPage(_episodeService.EpisodesWithoutFiles, v => MapToResource(v, includeSeries, false, includeImages));

View File

@ -59,25 +59,25 @@
"schema": {
"type": "object",
"properties": {
"Username": {
"username": {
"type": "string"
},
"Password": {
"password": {
"type": "string"
},
"RememberMe": {
"rememberMe": {
"type": "string"
}
}
},
"encoding": {
"Username": {
"username": {
"style": "form"
},
"Password": {
"password": {
"style": "form"
},
"RememberMe": {
"rememberMe": {
"style": "form"
}
}
@ -381,6 +381,40 @@
"tags": [
"Blocklist"
],
"parameters": [
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"format": "int32",
"default": 1
}
},
{
"name": "pageSize",
"in": "query",
"schema": {
"type": "integer",
"format": "int32",
"default": 10
}
},
{
"name": "sortKey",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "sortDirection",
"in": "query",
"schema": {
"$ref": "#/components/schemas/SortDirection"
}
}
],
"responses": {
"200": {
"description": "Success",
@ -1050,6 +1084,38 @@
"Cutoff"
],
"parameters": [
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"format": "int32",
"default": 1
}
},
{
"name": "pageSize",
"in": "query",
"schema": {
"type": "integer",
"format": "int32",
"default": 10
}
},
{
"name": "sortKey",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "sortDirection",
"in": "query",
"schema": {
"$ref": "#/components/schemas/SortDirection"
}
},
{
"name": "includeSeries",
"in": "query",
@ -1073,6 +1139,14 @@
"type": "boolean",
"default": false
}
},
{
"name": "monitored",
"in": "query",
"schema": {
"type": "boolean",
"default": true
}
}
],
"responses": {
@ -2220,6 +2294,38 @@
"History"
],
"parameters": [
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"format": "int32",
"default": 1
}
},
{
"name": "pageSize",
"in": "query",
"schema": {
"type": "integer",
"format": "int32",
"default": 10
}
},
{
"name": "sortKey",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "sortDirection",
"in": "query",
"schema": {
"$ref": "#/components/schemas/SortDirection"
}
},
{
"name": "includeSeries",
"in": "query",
@ -2233,6 +2339,29 @@
"schema": {
"type": "boolean"
}
},
{
"name": "eventType",
"in": "query",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "episodeId",
"in": "query",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "downloadId",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
@ -3627,6 +3756,47 @@
"tags": [
"Log"
],
"parameters": [
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"format": "int32",
"default": 1
}
},
{
"name": "pageSize",
"in": "query",
"schema": {
"type": "integer",
"format": "int32",
"default": 10
}
},
{
"name": "sortKey",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "sortDirection",
"in": "query",
"schema": {
"$ref": "#/components/schemas/SortDirection"
}
},
{
"name": "level",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
@ -4142,6 +4312,38 @@
"Missing"
],
"parameters": [
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"format": "int32",
"default": 1
}
},
{
"name": "pageSize",
"in": "query",
"schema": {
"type": "integer",
"format": "int32",
"default": 10
}
},
{
"name": "sortKey",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "sortDirection",
"in": "query",
"schema": {
"$ref": "#/components/schemas/SortDirection"
}
},
{
"name": "includeSeries",
"in": "query",
@ -4157,6 +4359,14 @@
"type": "boolean",
"default": false
}
},
{
"name": "monitored",
"in": "query",
"schema": {
"type": "boolean",
"default": true
}
}
],
"responses": {
@ -4325,21 +4535,21 @@
],
"parameters": [
{
"name": "RenameEpisodes",
"name": "renameEpisodes",
"in": "query",
"schema": {
"type": "boolean"
}
},
{
"name": "ReplaceIllegalCharacters",
"name": "replaceIllegalCharacters",
"in": "query",
"schema": {
"type": "boolean"
}
},
{
"name": "ColonReplacementFormat",
"name": "colonReplacementFormat",
"in": "query",
"schema": {
"type": "integer",
@ -4347,7 +4557,7 @@
}
},
{
"name": "MultiEpisodeStyle",
"name": "multiEpisodeStyle",
"in": "query",
"schema": {
"type": "integer",
@ -4355,91 +4565,91 @@
}
},
{
"name": "StandardEpisodeFormat",
"name": "standardEpisodeFormat",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "DailyEpisodeFormat",
"name": "dailyEpisodeFormat",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "AnimeEpisodeFormat",
"name": "animeEpisodeFormat",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "SeriesFolderFormat",
"name": "seriesFolderFormat",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "SeasonFolderFormat",
"name": "seasonFolderFormat",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "SpecialsFolderFormat",
"name": "specialsFolderFormat",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "IncludeSeriesTitle",
"name": "includeSeriesTitle",
"in": "query",
"schema": {
"type": "boolean"
}
},
{
"name": "IncludeEpisodeTitle",
"name": "includeEpisodeTitle",
"in": "query",
"schema": {
"type": "boolean"
}
},
{
"name": "IncludeQuality",
"name": "includeQuality",
"in": "query",
"schema": {
"type": "boolean"
}
},
{
"name": "ReplaceSpaces",
"name": "replaceSpaces",
"in": "query",
"schema": {
"type": "boolean"
}
},
{
"name": "Separator",
"name": "separator",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "NumberStyle",
"name": "numberStyle",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "Id",
"name": "id",
"in": "query",
"schema": {
"type": "integer",
@ -4447,7 +4657,7 @@
}
},
{
"name": "ResourceName",
"name": "resourceName",
"in": "query",
"schema": {
"type": "string"
@ -5212,6 +5422,38 @@
"Queue"
],
"parameters": [
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"format": "int32",
"default": 1
}
},
{
"name": "pageSize",
"in": "query",
"schema": {
"type": "integer",
"format": "int32",
"default": 10
}
},
{
"name": "sortKey",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "sortDirection",
"in": "query",
"schema": {
"$ref": "#/components/schemas/SortDirection"
}
},
{
"name": "includeUnknownSeriesItems",
"in": "query",
@ -7185,13 +7427,6 @@
"sortDirection": {
"$ref": "#/components/schemas/SortDirection"
},
"filters": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PagingResourceFilter"
},
"nullable": true
},
"totalRecords": {
"type": "integer",
"format": "int32"
@ -7402,7 +7637,7 @@
"type": "array",
"items": {
"type": "object",
"additionalProperties": { }
"additionalProperties": {}
},
"nullable": true
}
@ -7951,13 +8186,6 @@
"sortDirection": {
"$ref": "#/components/schemas/SortDirection"
},
"filters": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PagingResourceFilter"
},
"nullable": true
},
"totalRecords": {
"type": "integer",
"format": "int32"
@ -8200,13 +8428,6 @@
"sortDirection": {
"$ref": "#/components/schemas/SortDirection"
},
"filters": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PagingResourceFilter"
},
"nullable": true
},
"totalRecords": {
"type": "integer",
"format": "int32"
@ -8891,13 +9112,6 @@
"sortDirection": {
"$ref": "#/components/schemas/SortDirection"
},
"filters": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PagingResourceFilter"
},
"nullable": true
},
"totalRecords": {
"type": "integer",
"format": "int32"
@ -9549,20 +9763,6 @@
},
"additionalProperties": false
},
"PagingResourceFilter": {
"type": "object",
"properties": {
"key": {
"type": "string",
"nullable": true
},
"value": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
},
"ParseResource": {
"type": "object",
"properties": {
@ -10096,13 +10296,6 @@
"sortDirection": {
"$ref": "#/components/schemas/SortDirection"
},
"filters": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PagingResourceFilter"
},
"nullable": true
},
"totalRecords": {
"type": "integer",
"format": "int32"
@ -11628,10 +11821,10 @@
},
"security": [
{
"X-Api-Key": [ ]
"X-Api-Key": []
},
{
"apikey": [ ]
"apikey": []
}
]
}

View File

@ -4,7 +4,6 @@ using System.Linq;
using Microsoft.AspNetCore.Http;
using NzbDrone.Common.EnvironmentInfo;
using NzbDrone.Core.Datastore;
using NzbDrone.Core.Exceptions;
namespace Sonarr.Http.Extensions
{
@ -61,80 +60,6 @@ namespace Sonarr.Http.Extensions
return defaultValue;
}
public static PagingResource<TResource> ReadPagingResourceFromRequest<TResource>(this HttpRequest request)
{
if (!int.TryParse(request.Query["PageSize"].ToString(), out var pageSize))
{
pageSize = 10;
}
if (!int.TryParse(request.Query["Page"].ToString(), out var page))
{
page = 1;
}
var pagingResource = new PagingResource<TResource>
{
PageSize = pageSize,
Page = page,
Filters = new List<PagingResourceFilter>()
};
if (request.Query["SortKey"].Any())
{
var sortKey = request.Query["SortKey"].ToString();
if (!VALID_SORT_KEYS.Contains(sortKey) &&
!TableMapping.Mapper.IsValidSortKey(sortKey))
{
throw new BadRequestException($"Invalid sort key {sortKey}");
}
pagingResource.SortKey = sortKey;
if (request.Query["SortDirection"].Any())
{
pagingResource.SortDirection = request.Query["SortDirection"].ToString()
.Equals("ascending", StringComparison.InvariantCultureIgnoreCase)
? SortDirection.Ascending
: SortDirection.Descending;
}
}
// For backwards compatibility with v2
if (request.Query["FilterKey"].Any())
{
var filter = new PagingResourceFilter
{
Key = request.Query["FilterKey"].ToString()
};
if (request.Query["FilterValue"].Any())
{
filter.Value = request.Query["FilterValue"].ToString();
}
pagingResource.Filters.Add(filter);
}
// v3 uses filters in key=value format
foreach (var pair in request.Query)
{
if (EXCLUDED_KEYS.Contains(pair.Key))
{
continue;
}
pagingResource.Filters.Add(new PagingResourceFilter
{
Key = pair.Key,
Value = pair.Value.ToString()
});
}
return pagingResource;
}
public static PagingResource<TResource> ApplyToPage<TResource, TModel>(this PagingSpec<TModel> pagingSpec, Func<PagingSpec<TModel>, PagingSpec<TModel>> function, Converter<TModel, TResource> mapper)
{
pagingSpec = function(pagingSpec);

View File

@ -1,17 +1,39 @@
using System.Collections.Generic;
using System.ComponentModel;
using NzbDrone.Core.Datastore;
namespace Sonarr.Http
{
public class PagingRequestResource
{
[DefaultValue(1)]
public int? Page { get; set; }
[DefaultValue(10)]
public int? PageSize { get; set; }
public string SortKey { get; set; }
public SortDirection? SortDirection { get; set; }
}
public class PagingResource<TResource>
{
public int Page { get; set; }
public int PageSize { get; set; }
public string SortKey { get; set; }
public SortDirection SortDirection { get; set; }
public List<PagingResourceFilter> Filters { get; set; }
public int TotalRecords { get; set; }
public List<TResource> Records { get; set; }
public PagingResource()
{
}
public PagingResource(PagingRequestResource requestResource)
{
Page = requestResource.Page ?? 1;
PageSize = requestResource.PageSize ?? 10;
SortKey = requestResource.SortKey;
SortDirection = requestResource.SortDirection ?? SortDirection.Descending;
}
}
public static class PagingResourceMapper

View File

@ -1,8 +0,0 @@
namespace Sonarr.Http
{
public class PagingResourceFilter
{
public string Key { get; set; }
public string Value { get; set; }
}
}