docs(directory): 📝 document endpoints

services/Directory/FilterLists.Directory.Api/.editorconfig

@@ -0,0 +1,4 @@
+# To learn more about .editorconfig see https://aka.ms/editorconfigdocs
+
+[*.cs]
+dotnet_diagnostic.CS1591.severity = suggestion

services/Directory/FilterLists.Directory.Api/Controllers/LanguagesController.cs

@@ -18,6 +18,11 @@ public LanguagesController(IMemoryCache cache, IMediator mediator) : base(cache)
             _mediator = mediator;
         }
 
+        /// <summary>
+        /// Gets the languages targeted by FilterLists.
+        /// </summary>
+        /// <param name="cancellationToken">The cancellation token.</param>
+        /// <returns>The languages targeted by FilterLists.</returns>
         [HttpGet]
         [ProducesResponseType(typeof(IEnumerable<GetLanguages.LanguageVm>), StatusCodes.Status200OK)]
         [ProducesResponseType(StatusCodes.Status404NotFound)]

services/Directory/FilterLists.Directory.Api/Controllers/LicensesController.cs

@@ -18,6 +18,11 @@ public LicensesController(IMemoryCache cache, IMediator mediator) : base(cache)
             _mediator = mediator;
         }
 
+        /// <summary>
+        /// Gets the licenses applied to FilterLists.
+        /// </summary>
+        /// <param name="cancellationToken">The cancellation token.</param>
+        /// <returns>The licenses applied to FilterLists.</returns>
         [HttpGet]
         [ProducesResponseType(typeof(IEnumerable<GetLicenses.LicenseVm>), StatusCodes.Status200OK)]
         [ProducesResponseType(StatusCodes.Status404NotFound)]

services/Directory/FilterLists.Directory.Api/Controllers/ListsController.cs

@@ -19,6 +19,11 @@ public ListsController(IMemoryCache cache, IMediator mediator) : base(cache)
             _mediator = mediator;
         }
 
+        /// <summary>
+        /// Gets the FilterLists..
+        /// </summary>
+        /// <param name="cancellationToken">The cancellation token.</param>
+        /// <returns>The FilterLists.</returns>
         [HttpGet]
         [ProducesResponseType(typeof(IEnumerable<ListVm>), StatusCodes.Status200OK)]
         [ProducesResponseType(StatusCodes.Status404NotFound)]
@@ -27,13 +32,18 @@ public async Task<IActionResult> Get(CancellationToken cancellationToken)
             return await CacheGetOrCreateAsync(() => _mediator.Send(new GetLists.Query(), cancellationToken));
         }
 
+        /// <summary>
+        /// Gets the details of the FilterList.
+        /// </summary>
+        /// <param name="id">The identifier of the FilterList.</param>
+        /// <param name="cancellationToken">The cancellation token.</param>
+        /// <returns>The details of the FilterList.</returns>
         [HttpGet("{id}")]
         [ProducesResponseType(typeof(ListDetailsVm), StatusCodes.Status200OK)]
         [ProducesResponseType(StatusCodes.Status404NotFound)]
         public async Task<IActionResult> GetDetails(int id, CancellationToken cancellationToken)
         {
-            return await CacheGetOrCreateAsync(() => _mediator.Send(new GetListDetails.Query(id), cancellationToken),
-                id);
+            return await CacheGetOrCreateAsync(() => _mediator.Send(new GetListDetails.Query(id), cancellationToken), id);
         }
     }
 }

services/Directory/FilterLists.Directory.Api/Controllers/MaintainersController.cs

@@ -18,6 +18,11 @@ public MaintainersController(IMemoryCache cache, IMediator mediator) : base(cach
             _mediator = mediator;
         }
 
+        /// <summary>
+        /// Gets the maintainers of FilterLists.
+        /// </summary>
+        /// <param name="cancellationToken">The cancellation token.</param>
+        /// <returns>The maintainers of FilterLists.</returns>
         [HttpGet]
         [ProducesResponseType(typeof(IEnumerable<GetMaintainers.MaintainerVm>), StatusCodes.Status200OK)]
         [ProducesResponseType(StatusCodes.Status404NotFound)]

services/Directory/FilterLists.Directory.Api/Controllers/SoftwareController.cs

@@ -18,6 +18,11 @@ public SoftwareController(IMemoryCache cache, IMediator mediator) : base(cache)
             _mediator = mediator;
         }
 
+        /// <summary>
+        /// Gets the software that subscribes to FilterLists.
+        /// </summary>
+        /// <param name="cancellationToken">The cancellation token.</param>
+        /// <returns>The software that subscribes to FilterLists.</returns>
         [HttpGet]
         [ProducesResponseType(typeof(IEnumerable<GetSoftware.SoftwareVm>), StatusCodes.Status200OK)]
         [ProducesResponseType(StatusCodes.Status404NotFound)]

services/Directory/FilterLists.Directory.Api/Controllers/SyntaxesController.cs

@@ -18,6 +18,11 @@ public SyntaxesController(IMemoryCache cache, IMediator mediator) : base(cache)
             _mediator = mediator;
         }
 
+        /// <summary>
+        /// Gets the syntaxes of FilterLists.
+        /// </summary>
+        /// <param name="cancellationToken">The cancellation token.</param>
+        /// <returns>The syntaxes of FilterLists.</returns>
         [HttpGet]
         [ProducesResponseType(typeof(IEnumerable<GetSyntaxes.SyntaxVm>), StatusCodes.Status200OK)]
         [ProducesResponseType(StatusCodes.Status404NotFound)]

services/Directory/FilterLists.Directory.Api/Controllers/TagsController.cs

@@ -18,6 +18,11 @@ public TagsController(IMemoryCache cache, IMediator mediator) : base(cache)
             _mediator = mediator;
         }
 
+        /// <summary>
+        /// Gets the tags of FilterLists.
+        /// </summary>
+        /// <param name="cancellationToken">The cancellation token.</param>
+        /// <returns>The tags of FilterLists.</returns>
         [HttpGet]
         [ProducesResponseType(typeof(IEnumerable<GetTags.TagVm>), StatusCodes.Status200OK)]
         [ProducesResponseType(StatusCodes.Status404NotFound)]

services/Directory/FilterLists.Directory.Api/FilterLists.Directory.Api.csproj

@@ -4,6 +4,7 @@
         <TargetFramework>netcoreapp3.1</TargetFramework>
         <LangVersion>latest</LangVersion>
         <Nullable>enable</Nullable>
+        <GenerateDocumentationFile>true</GenerateDocumentationFile>
         <PublishReadyToRunShowWarnings>true</PublishReadyToRunShowWarnings>
         <RuntimeIdentifiers>linux-musl-x64;win10-x64</RuntimeIdentifiers>
     </PropertyGroup>

services/Directory/FilterLists.Directory.Api/SwaggerExtensions.cs

@@ -1,5 +1,7 @@
 using System;
 using System.Collections.Generic;
+using System.IO;
+using System.Reflection;
 using Microsoft.AspNetCore.Builder;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.OpenApi.Models;
@@ -25,6 +27,10 @@ public static void AddSwaggerGen(this IServiceCollection services)
                         Url = new Uri("https://github.com/collinbarrett/FilterLists/blob/master/LICENSE")
                     }
                 });
+
+                var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
+                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
+                o.IncludeXmlComments(xmlPath);
             });
         }