consolidate OpenAPI categories and deprecate startup routes (#16757)

Jellyfin.Api/Controllers/DashboardController.cs

@@ -20,6 +20,7 @@ namespace Jellyfin.Api.Controllers;
 /// The dashboard controller.
 /// </summary>
 [Route("")]
+[Tags("Plugin")]
 public class DashboardController : BaseJellyfinApiController
 {
     private readonly ILogger<DashboardController> _logger;

Jellyfin.Api/Controllers/InstantMixController.cs

@@ -196,6 +196,7 @@ public class InstantMixController : BaseJellyfinApiController
     /// <returns>A <see cref="QueryResult{BaseItemDto}"/> with the playlist items.</returns>
     [HttpGet("MusicGenres/{name}/InstantMix")]
     [ProducesResponseType(StatusCodes.Status200OK)]
+    [Obsolete("Use GetInstantMixFromItem")]
     public ActionResult<QueryResult<BaseItemDto>> GetInstantMixFromMusicGenreByName(
         [FromRoute, Required] string name,
         [FromQuery] Guid? userId,
@@ -359,7 +360,7 @@ public class InstantMixController : BaseJellyfinApiController
     [HttpGet("MusicGenres/InstantMix")]
     [ProducesResponseType(StatusCodes.Status200OK)]
     [ProducesResponseType(StatusCodes.Status404NotFound)]
-    [Obsolete("Use GetInstantMixFromMusicGenreByName")]
+    [Obsolete("Use GetInstantMixFromItem")]
     public ActionResult<QueryResult<BaseItemDto>> GetInstantMixFromMusicGenreById(
         [FromQuery, Required] Guid id,
         [FromQuery] Guid? userId,

Jellyfin.Api/Controllers/ItemRefreshController.cs

@@ -20,6 +20,7 @@ namespace Jellyfin.Api.Controllers;
 /// </summary>
 [Route("Items")]
 [Authorize(Policy = Policies.RequiresElevation)]
+[Tags("Library")]
 public class ItemRefreshController : BaseJellyfinApiController
 {
     private readonly ILibraryManager _libraryManager;

Jellyfin.Api/Controllers/ItemsController.cs

@@ -31,7 +31,7 @@ namespace Jellyfin.Api.Controllers;
 /// </summary>
 [Route("")]
 [Authorize]
-[Tags("Item")]
+[Tags("Library")]
 public class ItemsController : BaseJellyfinApiController
 {
     private readonly IUserManager _userManager;
@@ -955,6 +955,7 @@ public class ItemsController : BaseJellyfinApiController
     [HttpGet("UserItems/{itemId}/UserData")]
     [ProducesResponseType(StatusCodes.Status200OK)]
     [ProducesResponseType(StatusCodes.Status404NotFound)]
+    [Tags("UserData")]
     public ActionResult<UserItemDataDto?> GetItemUserData(
         [FromQuery] Guid? userId,
         [FromRoute, Required] Guid itemId)
@@ -1010,6 +1011,7 @@ public class ItemsController : BaseJellyfinApiController
     [HttpPost("UserItems/{itemId}/UserData")]
     [ProducesResponseType(StatusCodes.Status200OK)]
     [ProducesResponseType(StatusCodes.Status404NotFound)]
+    [Tags("UserData")]
     public ActionResult<UserItemDataDto?> UpdateItemUserData(
         [FromQuery] Guid? userId,
         [FromRoute, Required] Guid itemId,

Jellyfin.Api/Controllers/PlaystateController.cs

@@ -72,6 +72,7 @@ public class PlaystateController : BaseJellyfinApiController
     [HttpPost("UserPlayedItems/{itemId}")]
     [ProducesResponseType(StatusCodes.Status200OK)]
     [ProducesResponseType(StatusCodes.Status404NotFound)]
+    [Tags("UserData")]
     public async Task<ActionResult<UserItemDataDto?>> MarkPlayedItem(
         [FromQuery] Guid? userId,
         [FromRoute, Required] Guid itemId,
@@ -138,6 +139,7 @@ public class PlaystateController : BaseJellyfinApiController
     [HttpDelete("UserPlayedItems/{itemId}")]
     [ProducesResponseType(StatusCodes.Status200OK)]
     [ProducesResponseType(StatusCodes.Status404NotFound)]
+    [Tags("UserData")]
     public async Task<ActionResult<UserItemDataDto?>> MarkUnplayedItem(
         [FromQuery] Guid? userId,
         [FromRoute, Required] Guid itemId)

Jellyfin.Api/Controllers/SessionController.cs

@@ -432,6 +432,7 @@ public class SessionController : BaseJellyfinApiController
     /// <returns>An <see cref="IEnumerable{NameIdPair}"/> with the auth providers.</returns>
     [HttpGet("Auth/Providers")]
     [Authorize(Policy = Policies.RequiresElevation)]
+    [Tags("Authentication")]
     [ProducesResponseType(StatusCodes.Status200OK)]
     public ActionResult<IEnumerable<NameIdPair>> GetAuthProviders()
     {
@@ -444,6 +445,7 @@ public class SessionController : BaseJellyfinApiController
     /// <response code="200">Password reset providers retrieved.</response>
     /// <returns>An <see cref="IEnumerable{NameIdPair}"/> with the password reset providers.</returns>
     [HttpGet("Auth/PasswordResetProviders")]
+    [Tags("Authentication")]
     [ProducesResponseType(StatusCodes.Status200OK)]
     [Authorize(Policy = Policies.RequiresElevation)]
     public ActionResult<IEnumerable<NameIdPair>> GetPasswordResetProviders()

Jellyfin.Api/Controllers/StartupController.cs

@@ -1,7 +1,6 @@
 using System;
 using System.ComponentModel.DataAnnotations;
 using System.Threading.Tasks;
-using Jellyfin.Api.Constants;
 using Jellyfin.Api.Models.StartupDtos;
 using MediaBrowser.Common.Api;
 using MediaBrowser.Common.Net;
@@ -54,6 +53,7 @@ public class StartupController : BaseJellyfinApiController
     /// <returns>An <see cref="OkResult"/> containing the initial startup wizard configuration.</returns>
     [HttpGet("Configuration")]
     [ProducesResponseType(StatusCodes.Status200OK)]
+    [Obsolete("Use configuration endpoints")]
     public ActionResult<StartupConfigurationDto> GetStartupConfiguration()
     {
         return new StartupConfigurationDto
@@ -73,6 +73,7 @@ public class StartupController : BaseJellyfinApiController
     /// <returns>A <see cref="NoContentResult"/> indicating success.</returns>
     [HttpPost("Configuration")]
     [ProducesResponseType(StatusCodes.Status204NoContent)]
+    [Obsolete("Use configuration endpoints")]
     public ActionResult UpdateInitialConfiguration([FromBody, Required] StartupConfigurationDto startupConfiguration)
     {
         _config.Configuration.ServerName = startupConfiguration.ServerName ?? string.Empty;
@@ -91,6 +92,7 @@ public class StartupController : BaseJellyfinApiController
     /// <returns>A <see cref="NoContentResult"/> indicating success.</returns>
     [HttpPost("RemoteAccess")]
     [ProducesResponseType(StatusCodes.Status204NoContent)]
+    [Obsolete("Use configuration endpoints")]
     public ActionResult SetRemoteAccess([FromBody, Required] StartupRemoteAccessDto startupRemoteAccessDto)
     {
         NetworkConfiguration settings = _config.GetNetworkConfiguration();
@@ -107,6 +109,7 @@ public class StartupController : BaseJellyfinApiController
     [HttpGet("User")]
     [HttpGet("FirstUser", Name = "GetFirstUser_2")]
     [ProducesResponseType(StatusCodes.Status200OK)]
+    [Obsolete("Use authentication endpoints")]
     public async Task<StartupUserDto> GetFirstUser()
     {
         // TODO: Remove this method when startup wizard no longer requires an existing user.

Jellyfin.Api/Controllers/UserController.cs

@@ -208,6 +208,7 @@ public class UserController : BaseJellyfinApiController
     /// <returns>A <see cref="Task"/> containing an <see cref="AuthenticationRequest"/> with information about the new session.</returns>
     [HttpPost("AuthenticateByName")]
     [ProducesResponseType(StatusCodes.Status200OK)]
+    [Tags("Authentication")]
     public async Task<ActionResult<AuthenticationResult>> AuthenticateUserByName([FromBody, Required] AuthenticateUserByName request)
     {
         var auth = await _authContext.GetAuthorizationInfo(Request).ConfigureAwait(false);
@@ -243,6 +244,7 @@ public class UserController : BaseJellyfinApiController
     /// <returns>A <see cref="Task"/> containing an <see cref="AuthenticationRequest"/> with information about the new session.</returns>
     [HttpPost("AuthenticateWithQuickConnect")]
     [ProducesResponseType(StatusCodes.Status200OK)]
+    [Tags("Authentication")]
     public ActionResult<AuthenticationResult> AuthenticateWithQuickConnect([FromBody, Required] QuickConnectDto request)
     {
         try
@@ -538,6 +540,7 @@ public class UserController : BaseJellyfinApiController
     /// <returns>A <see cref="Task"/> containing a <see cref="ForgotPasswordResult"/>.</returns>
     [HttpPost("ForgotPassword")]
     [ProducesResponseType(StatusCodes.Status200OK)]
+    [Tags("Authentication")]
     public async Task<ActionResult<ForgotPasswordResult>> ForgotPassword([FromBody, Required] ForgotPasswordDto forgotPasswordRequest)
     {
         var ip = HttpContext.GetNormalizedRemoteIP();
@@ -562,6 +565,7 @@ public class UserController : BaseJellyfinApiController
     /// <returns>A <see cref="Task"/> containing a <see cref="PinRedeemResult"/>.</returns>
     [HttpPost("ForgotPassword/Pin")]
     [ProducesResponseType(StatusCodes.Status200OK)]
+    [Tags("Authentication")]
     public async Task<ActionResult<PinRedeemResult>> ForgotPasswordPin([FromBody, Required] ForgotPasswordPinDto forgotPasswordPinRequest)
     {
         var result = await _userManager.RedeemPasswordResetPin(forgotPasswordPinRequest.Pin).ConfigureAwait(false);

Jellyfin.Api/Controllers/UserLibraryController.cs

@@ -31,6 +31,7 @@ namespace Jellyfin.Api.Controllers;
 /// </summary>
 [Route("")]
 [Authorize]
+[Tags("Library")]
 public class UserLibraryController : BaseJellyfinApiController
 {
     private readonly IUserManager _userManager;
@@ -212,6 +213,7 @@ public class UserLibraryController : BaseJellyfinApiController
     /// <returns>An <see cref="OkResult"/> containing the <see cref="UserItemDataDto"/>.</returns>
     [HttpPost("UserFavoriteItems/{itemId}")]
     [ProducesResponseType(StatusCodes.Status200OK)]
+    [Tags("UserData")]
     public ActionResult<UserItemDataDto> MarkFavoriteItem(
         [FromQuery] Guid? userId,
         [FromRoute, Required] Guid itemId)
@@ -259,6 +261,7 @@ public class UserLibraryController : BaseJellyfinApiController
     /// <returns>An <see cref="OkResult"/> containing the <see cref="UserItemDataDto"/>.</returns>
     [HttpDelete("UserFavoriteItems/{itemId}")]
     [ProducesResponseType(StatusCodes.Status200OK)]
+    [Tags("UserData")]
     public ActionResult<UserItemDataDto> UnmarkFavoriteItem(
         [FromQuery] Guid? userId,
         [FromRoute, Required] Guid itemId)
@@ -306,6 +309,7 @@ public class UserLibraryController : BaseJellyfinApiController
     /// <returns>An <see cref="OkResult"/> containing the <see cref="UserItemDataDto"/>.</returns>
     [HttpDelete("UserItems/{itemId}/Rating")]
     [ProducesResponseType(StatusCodes.Status200OK)]
+    [Tags("UserData")]
     public ActionResult<UserItemDataDto?> DeleteUserItemRating(
         [FromQuery] Guid? userId,
         [FromRoute, Required] Guid itemId)
@@ -354,6 +358,7 @@ public class UserLibraryController : BaseJellyfinApiController
     /// <returns>An <see cref="OkResult"/> containing the <see cref="UserItemDataDto"/>.</returns>
     [HttpPost("UserItems/{itemId}/Rating")]
     [ProducesResponseType(StatusCodes.Status200OK)]
+    [Tags("UserData")]
     public ActionResult<UserItemDataDto?> UpdateUserItemRating(
         [FromQuery] Guid? userId,
         [FromRoute, Required] Guid itemId,