From 38ec742db6336e5626cbedf1947f420a85e14e4a Mon Sep 17 00:00:00 2001
From: Zoe Roux <zoe.roux@sdg.moe>
Date: Thu, 23 Sep 2021 13:49:25 +0200
Subject: [PATCH] API: Documenting the track's api

---
 .../Models/Resources/Track.cs                 |  2 +-
 src/Kyoo.Core/Views/TrackApi.cs               | 63 +++++++++++--------
 tests/Kyoo.Tests/Database/TestSample.cs       | 31 +++++----
 3 files changed, 56 insertions(+), 40 deletions(-)

diff --git a/src/Kyoo.Abstractions/Models/Resources/Track.cs b/src/Kyoo.Abstractions/Models/Resources/Track.cs
index 14f471b0..8e41c7ee 100644
--- a/src/Kyoo.Abstractions/Models/Resources/Track.cs
+++ b/src/Kyoo.Abstractions/Models/Resources/Track.cs
@@ -52,7 +52,7 @@ namespace Kyoo.Abstractions.Models
 		Subtitle = 3,
 
 		/// <summary>
-		/// The stream is an attachement (a font, an image or something else).
+		/// The stream is an attachment (a font, an image or something else).
 		/// Only fonts are handled by kyoo but they are not saved to the database.
 		/// </summary>
 		Attachment = 4
diff --git a/src/Kyoo.Core/Views/TrackApi.cs b/src/Kyoo.Core/Views/TrackApi.cs
index 7075bcbc..1d2e89cb 100644
--- a/src/Kyoo.Core/Views/TrackApi.cs
+++ b/src/Kyoo.Core/Views/TrackApi.cs
@@ -16,58 +16,69 @@
 // You should have received a copy of the GNU General Public License
 // along with Kyoo. If not, see <https://www.gnu.org/licenses/>.
 
-using System.Linq;
 using System.Threading.Tasks;
 using Kyoo.Abstractions.Controllers;
 using Kyoo.Abstractions.Models;
-using Kyoo.Abstractions.Models.Exceptions;
+using Kyoo.Abstractions.Models.Attributes;
 using Kyoo.Abstractions.Models.Permissions;
+using Kyoo.Abstractions.Models.Utils;
 using Kyoo.Core.Models.Options;
+using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.Extensions.Options;
+using static Kyoo.Abstractions.Models.Utils.Constants;
 
 namespace Kyoo.Core.Api
 {
-	[Route("api/track")]
+	/// <summary>
+	/// Information about one or multiple <see cref="Track"/>.
+	/// </summary>
 	[Route("api/tracks")]
+	[Route("api/track", Order = AlternativeRoute)]
 	[ApiController]
 	[PartialPermission(nameof(Track))]
+	[ApiDefinition("Tracks", Group = ResourcesGroup)]
 	public class TrackApi : CrudApi<Track>
 	{
+		/// <summary>
+		/// The library manager used to modify or retrieve information in the data store.
+		/// </summary>
 		private readonly ILibraryManager _libraryManager;
 
+		/// <summary>
+		/// Create a new <see cref="TrackApi"/>.
+		/// </summary>
+		/// <param name="libraryManager">
+		/// The library manager used to modify or retrieve information in the data store.
+		/// </param>
+		/// <param name="options">
+		/// Options used to retrieve the base URL of Kyoo.
+		/// </param>
 		public TrackApi(ILibraryManager libraryManager, IOptions<BasicOptions> options)
 			: base(libraryManager.TrackRepository, options.Value.PublicUrl)
 		{
 			_libraryManager = libraryManager;
 		}
 
-		[HttpGet("{id:int}/episode")]
+		/// <summary>
+		/// Get track's episode
+		/// </summary>
+		/// <remarks>
+		/// Get the episode that uses this track.
+		/// </remarks>
+		/// <param name="identifier">The ID or slug of the <see cref="Track"/>.</param>
+		/// <returns>The episode that uses this track.</returns>
+		/// <response code="404">No track with the given ID or slug could be found.</response>
+		[HttpGet("{identifier:id}/episode")]
 		[PartialPermission(Kind.Read)]
-		public async Task<ActionResult<Episode>> GetEpisode(int id)
+		[ProducesResponseType(StatusCodes.Status200OK)]
+		[ProducesResponseType(StatusCodes.Status404NotFound)]
+		public async Task<ActionResult<Episode>> GetEpisode(Identifier identifier)
 		{
-			try
-			{
-				return await _libraryManager.Get<Episode>(x => x.Tracks.Any(y => y.ID == id));
-			}
-			catch (ItemNotFoundException)
-			{
+			Episode ret = await _libraryManager.GetOrDefault(identifier.IsContainedIn<Episode, Track>(x => x.Tracks));
+			if (ret == null)
 				return NotFound();
-			}
-		}
-
-		[HttpGet("{slug}/episode")]
-		[PartialPermission(Kind.Read)]
-		public async Task<ActionResult<Episode>> GetEpisode(string slug)
-		{
-			try
-			{
-				return await _libraryManager.Get<Episode>(x => x.Tracks.Any(y => y.Slug == slug));
-			}
-			catch (ItemNotFoundException)
-			{
-				return NotFound();
-			}
+			return ret;
 		}
 	}
 }
diff --git a/tests/Kyoo.Tests/Database/TestSample.cs b/tests/Kyoo.Tests/Database/TestSample.cs
index 13b9a0e9..a7327753 100644
--- a/tests/Kyoo.Tests/Database/TestSample.cs
+++ b/tests/Kyoo.Tests/Database/TestSample.cs
@@ -241,20 +241,25 @@ namespace Kyoo.Tests
 			},
 			{
 				typeof(Track),
-				() => new Track
+				() =>
 				{
-					ID = 1,
-					EpisodeID = 1,
-					Codec = "subrip",
-					Language = "eng",
-					Path = "/path",
-					Title = "Subtitle track",
-					Type = StreamType.Subtitle,
-					EpisodeSlug = Get<Episode>().Slug,
-					IsDefault = true,
-					IsExternal = false,
-					IsForced = false,
-					TrackIndex = 1
+					Track ret =  new()
+					{
+						ID = 1,
+						EpisodeID = 1,
+						Codec = "subrip",
+						Language = "eng",
+						Path = "/path",
+						Title = "Subtitle track",
+						Episode = Get<Episode>(),
+						Type = StreamType.Subtitle,
+						IsDefault = true,
+						IsExternal = false,
+						IsForced = false,
+						TrackIndex = 1
+					};
+					ret.Episode = null;
+					return ret;
 				}
 			},
 			{