diff --git a/src/Kyoo.Core/Views/CollectionApi.cs b/src/Kyoo.Core/Views/CollectionApi.cs index 93c54520..e491effa 100644 --- a/src/Kyoo.Core/Views/CollectionApi.cs +++ b/src/Kyoo.Core/Views/CollectionApi.cs @@ -31,14 +31,28 @@ using static Kyoo.Abstractions.Models.Utils.Constants; namespace Kyoo.Core.Api { + /// + /// Information about one or multiple . + /// [Route("api/collections")] [Route("api/collection", Order = AlternativeRoute)] [ApiController] [PartialPermission(nameof(CollectionApi))] public class CollectionApi : CrudApi { + /// + /// The library manager used to modify or retrieve information about the data store. + /// private readonly ILibraryManager _libraryManager; + + /// + /// The file manager used to send images. + /// private readonly IFileSystem _files; + + /// + /// The thumbnail manager used to retrieve images paths. + /// private readonly IThumbnailsManager _thumbs; public CollectionApi(ILibraryManager libraryManager, @@ -52,6 +66,20 @@ namespace Kyoo.Core.Api _thumbs = thumbs; } + /// + /// Lists that are contained in the with id . + /// + /// The ID of the . + /// A key to sort shows by. See for more information. + /// An optional show's ID to start the query from this specific item. + /// + /// An optional list of filters. See for more details. + /// + /// The number of shows to return. + /// A page of shows. + /// A page of shows. + /// or is invalid. + /// No collection with the ID could be found. [HttpGet("{id:int}/shows")] [HttpGet("{id:int}/show", Order = AlternativeRoute)] [PartialPermission(Kind.Read)] diff --git a/src/Kyoo.Core/Views/Helper/CrudApi.cs b/src/Kyoo.Core/Views/Helper/CrudApi.cs index 8bbc47dc..4f795f47 100644 --- a/src/Kyoo.Core/Views/Helper/CrudApi.cs +++ b/src/Kyoo.Core/Views/Helper/CrudApi.cs @@ -28,21 +28,47 @@ using Microsoft.AspNetCore.Mvc; namespace Kyoo.Core.Api { + /// + /// A base class to handle CRUD operations on a specific resource type . + /// + /// The type of resource to make CRUD apis for. [ApiController] [ResourceView] public class CrudApi : ControllerBase where T : class, IResource { + /// + /// The repository of the resource, used to retrieve, save and do operations on the baking store. + /// private readonly IRepository _repository; + /// + /// The base URL of Kyoo. This will be used to create links for images and . + /// protected Uri BaseURL { get; } + /// + /// Create a new using the given repository and base url. + /// + /// + /// The repository to use as a baking store for the type . + /// + /// + /// The base URL of Kyoo to use to create links. + /// public CrudApi(IRepository repository, Uri baseURL) { _repository = repository; BaseURL = baseURL; } + /// + /// Get a by ID. + /// + /// The ID of the resource to retrieve. + /// The retrieved . + /// The exist and is returned. + /// A resource with the ID does not exist. [HttpGet("{id:int}")] [PartialPermission(Kind.Read)] public virtual async Task> Get(int id) diff --git a/src/Kyoo.Swagger/SwaggerModule.cs b/src/Kyoo.Swagger/SwaggerModule.cs index 92c947eb..9343cc33 100644 --- a/src/Kyoo.Swagger/SwaggerModule.cs +++ b/src/Kyoo.Swagger/SwaggerModule.cs @@ -66,9 +66,7 @@ namespace Kyoo.Swagger } }); - foreach (string documentation in Directory.GetFiles(AppContext.BaseDirectory, "*.xml")) - options.IncludeXmlComments(documentation); - + options.LoadXmlDocumentation(); options.UseAllOfForInheritance(); options.SwaggerGeneratorOptions.SortKeySelector = x => x.RelativePath; options.DocInclusionPredicate((_, apiDescription) diff --git a/src/Kyoo.Swagger/XmlDocumentationLoader.cs b/src/Kyoo.Swagger/XmlDocumentationLoader.cs new file mode 100644 index 00000000..b580e351 --- /dev/null +++ b/src/Kyoo.Swagger/XmlDocumentationLoader.cs @@ -0,0 +1,68 @@ +// Kyoo - A portable and vast media library solution. +// Copyright (c) Kyoo. +// +// See AUTHORS.md and LICENSE file in the project root for full license information. +// +// Kyoo is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// any later version. +// +// Kyoo is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. +// +// You should have received a copy of the GNU General Public License +// along with Kyoo. If not, see . + +using System; +using System.Collections.Generic; +using System.IO; +using System.Linq; +using System.Xml.Linq; +using System.Xml.XPath; +using Microsoft.Extensions.DependencyInjection; +using Swashbuckle.AspNetCore.SwaggerGen; + +namespace Kyoo.Swagger +{ + /// + /// A static class containing a custom way to include XML to Swagger. + /// + public static class XmlDocumentationLoader + { + /// + /// Inject human-friendly descriptions for Operations, Parameters and Schemas based on XML Comment files + /// + /// The swagger generator to add documentation to. + public static void LoadXmlDocumentation(this SwaggerGenOptions options) + { + ICollection docs = Directory.GetFiles(AppContext.BaseDirectory, "*.xml") + .Select(XDocument.Load) + .ToList(); + Dictionary elements = docs + .SelectMany(x => x.XPathSelectElements("/doc/members/member[@name and not(inheritdoc)]")) + .ToDictionary(x => x.Attribute("name")!.Value, x => x); + + foreach (XElement doc in docs + .SelectMany(x => x.XPathSelectElements("/doc/members/member[inheritdoc[@cref]]"))) + { + if (elements.TryGetValue(doc.Attribute("cref")!.Value, out XElement member)) + doc.Element("inheritdoc")!.ReplaceWith(member); + } + foreach (XElement doc in docs.SelectMany(x => x.XPathSelectElements("//see[@cref]"))) + { + string fullName = doc.Attribute("cref")!.Value; + string shortName = fullName[(fullName.LastIndexOf('.') + 1)..]; + // TODO won't work with fully qualified methods. + if (fullName.StartsWith("M:")) + shortName += "()"; + doc.ReplaceWith(shortName); + } + + foreach (XDocument doc in docs) + options.IncludeXmlComments(() => new XPathDocument(doc.CreateReader()), true); + } + } +}