Merge pull request #5069 from crobibero/obsolete-param

Jellyfin.Api/Attributes/ParameterObsoleteAttribute.cs

@@ -0,0 +1,12 @@
+using System;
+
+namespace Jellyfin.Api.Attributes
+{
+    /// <summary>
+    /// Attribute to mark a parameter as obsolete.
+    /// </summary>
+    [AttributeUsage(AttributeTargets.Parameter)]
+    public class ParameterObsoleteAttribute : Attribute
+    {
+    }
+}

Jellyfin.Api/Controllers/MediaInfoController.cs

@@ -83,6 +83,7 @@ namespace Jellyfin.Api.Controllers
         /// </summary>
         /// <remarks>
         /// For backwards compatibility parameters can be sent via Query or Body, with Query having higher precedence.
+        /// Query parameters are obsolete.
         /// </remarks>
         /// <param name="itemId">The item id.</param>
         /// <param name="userId">The user id.</param>
@@ -106,20 +107,20 @@ namespace Jellyfin.Api.Controllers
         [ProducesResponseType(StatusCodes.Status200OK)]
         public async Task<ActionResult<PlaybackInfoResponse>> GetPostedPlaybackInfo(
             [FromRoute, Required] Guid itemId,
-            [FromQuery] Guid? userId,
-            [FromQuery] int? maxStreamingBitrate,
-            [FromQuery] long? startTimeTicks,
-            [FromQuery] int? audioStreamIndex,
-            [FromQuery] int? subtitleStreamIndex,
-            [FromQuery] int? maxAudioChannels,
-            [FromQuery] string? mediaSourceId,
-            [FromQuery] string? liveStreamId,
-            [FromQuery] bool? autoOpenLiveStream,
-            [FromQuery] bool? enableDirectPlay,
-            [FromQuery] bool? enableDirectStream,
-            [FromQuery] bool? enableTranscoding,
-            [FromQuery] bool? allowVideoStreamCopy,
-            [FromQuery] bool? allowAudioStreamCopy,
+            [FromQuery, ParameterObsolete] Guid? userId,
+            [FromQuery, ParameterObsolete] int? maxStreamingBitrate,
+            [FromQuery, ParameterObsolete] long? startTimeTicks,
+            [FromQuery, ParameterObsolete] int? audioStreamIndex,
+            [FromQuery, ParameterObsolete] int? subtitleStreamIndex,
+            [FromQuery, ParameterObsolete] int? maxAudioChannels,
+            [FromQuery, ParameterObsolete] string? mediaSourceId,
+            [FromQuery, ParameterObsolete] string? liveStreamId,
+            [FromQuery, ParameterObsolete] bool? autoOpenLiveStream,
+            [FromQuery, ParameterObsolete] bool? enableDirectPlay,
+            [FromQuery, ParameterObsolete] bool? enableDirectStream,
+            [FromQuery, ParameterObsolete] bool? enableTranscoding,
+            [FromQuery, ParameterObsolete] bool? allowVideoStreamCopy,
+            [FromQuery, ParameterObsolete] bool? allowAudioStreamCopy,
             [FromBody(EmptyBodyBehavior = EmptyBodyBehavior.Allow)] PlaybackInfoDto? playbackInfoDto)
         {
             var authInfo = _authContext.GetAuthorizationInfo(Request);

Jellyfin.Api/Controllers/PlaylistsController.cs

@@ -3,6 +3,7 @@ using System.Collections.Generic;
 using System.ComponentModel.DataAnnotations;
 using System.Linq;
 using System.Threading.Tasks;
+using Jellyfin.Api.Attributes;
 using Jellyfin.Api.Constants;
 using Jellyfin.Api.Extensions;
 using Jellyfin.Api.Helpers;
@@ -57,6 +58,7 @@ namespace Jellyfin.Api.Controllers
         /// </summary>
         /// <remarks>
         /// For backwards compatibility parameters can be sent via Query or Body, with Query having higher precedence.
+        /// Query parameters are obsolete.
         /// </remarks>
         /// <param name="name">The playlist name.</param>
         /// <param name="ids">The item ids.</param>
@@ -70,10 +72,10 @@ namespace Jellyfin.Api.Controllers
         [HttpPost]
         [ProducesResponseType(StatusCodes.Status200OK)]
         public async Task<ActionResult<PlaylistCreationResult>> CreatePlaylist(
-            [FromQuery] string? name,
-            [FromQuery, ModelBinder(typeof(CommaDelimitedArrayModelBinder))] IReadOnlyList<Guid> ids,
-            [FromQuery] Guid? userId,
-            [FromQuery] string? mediaType,
+            [FromQuery, ParameterObsolete] string? name,
+            [FromQuery, ModelBinder(typeof(CommaDelimitedArrayModelBinder)), ParameterObsolete] IReadOnlyList<Guid> ids,
+            [FromQuery, ParameterObsolete] Guid? userId,
+            [FromQuery, ParameterObsolete] string? mediaType,
             [FromBody(EmptyBodyBehavior = EmptyBodyBehavior.Allow)] CreatePlaylistDto? createPlaylistRequest)
         {
             if (ids.Count == 0)

Jellyfin.Server/Extensions/ApiServiceCollectionExtensions.cs

@@ -1,13 +1,10 @@
 using System;
 using System.Collections.Generic;
-using System.Globalization;
 using System.IO;
 using System.Linq;
 using System.Net;
 using System.Net.Sockets;
 using System.Reflection;
-using System.Runtime.CompilerServices;
-using System.Text;
 using Emby.Server.Implementations;
 using Jellyfin.Api.Auth;
 using Jellyfin.Api.Auth.DefaultAuthorizationPolicy;
@@ -25,7 +22,6 @@ using Jellyfin.Api.Controllers;
 using Jellyfin.Api.ModelBinders;
 using Jellyfin.Data.Enums;
 using Jellyfin.Networking.Configuration;
-using Jellyfin.Networking.Manager;
 using Jellyfin.Server.Configuration;
 using Jellyfin.Server.Filters;
 using Jellyfin.Server.Formatters;
@@ -317,6 +313,7 @@ namespace Jellyfin.Server.Extensions
 
                 c.OperationFilter<SecurityRequirementsOperationFilter>();
                 c.OperationFilter<FileResponseFilter>();
+                c.OperationFilter<ParameterObsoleteFilter>();
                 c.DocumentFilter<WebsocketModelFilter>();
             });
         }

Jellyfin.Server/Filters/ParameterObsoleteFilter.cs

@@ -0,0 +1,37 @@
+using System;
+using System.Linq;
+using Jellyfin.Api.Attributes;
+using Microsoft.AspNetCore.Mvc.ApiExplorer;
+using Microsoft.OpenApi.Models;
+using Swashbuckle.AspNetCore.SwaggerGen;
+
+namespace Jellyfin.Server.Filters
+{
+    /// <summary>
+    /// Mark parameter as deprecated if it has the <see cref="ParameterObsoleteAttribute"/>.
+    /// </summary>
+    public class ParameterObsoleteFilter : IOperationFilter
+    {
+        /// <inheritdoc />
+        public void Apply(OpenApiOperation operation, OperationFilterContext context)
+        {
+            foreach (var parameterDescription in context.ApiDescription.ParameterDescriptions)
+            {
+                if (parameterDescription
+                    .CustomAttributes()
+                    .OfType<ParameterObsoleteAttribute>()
+                    .Any())
+                {
+                    foreach (var parameter in operation.Parameters)
+                    {
+                        if (parameter.Name.Equals(parameterDescription.Name, StringComparison.Ordinal))
+                        {
+                            parameter.Deprecated = true;
+                            break;
+                        }
+                    }
+                }
+            }
+        }
+    }
+}