From a19713e63fed6efb9686c2c298ddbdb11b18376c Mon Sep 17 00:00:00 2001 From: "Collin M. Barrett" Date: Sat, 27 Nov 2021 14:57:33 -0600 Subject: [PATCH] =?UTF-8?q?docs(dir):=20=F0=9F=93=84=20doc=20GET/POST=20li?= =?UTF-8?q?sts=20vms?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../Models/ListDetailsVm.cs | 138 +++++++++++++++- .../Models/ListVm.cs | 50 +++++- .../Controllers/ListsController.cs | 2 +- .../Commands/CreateList.cs | 147 +++++++++++++++--- .../Queries/GetLanguages.cs | 4 +- .../Queries/GetLicenses.cs | 2 +- .../Queries/GetListDetails.cs | 11 +- 7 files changed, 323 insertions(+), 31 deletions(-) diff --git a/services/Directory/FilterLists.Directory.Api.Contracts/Models/ListDetailsVm.cs b/services/Directory/FilterLists.Directory.Api.Contracts/Models/ListDetailsVm.cs index 3a127952b..1c63ca7e6 100644 --- a/services/Directory/FilterLists.Directory.Api.Contracts/Models/ListDetailsVm.cs +++ b/services/Directory/FilterLists.Directory.Api.Contracts/Models/ListDetailsVm.cs @@ -2,35 +2,171 @@ public record ListDetailsVm { + /// + /// The identifier. + /// + /// 301 public long Id { get; init; } + + /// + /// The unique name in title case. + /// + /// EasyList public string Name { get; init; } = default!; + + /// + /// The brief description in English (preferably quoted from the project). + /// + /// + /// EasyList is the primary filter list that removes most adverts from international web pages, including unwanted + /// frames, images, and objects. It is the most popular list used by many ad blockers and forms the basis of over a + /// dozen combination and supplementary filter lists. + /// public string? Description { get; init; } - public long? LicenseId { get; init; } + + /// + /// The identifier of the License under which this FilterList is released. + /// + /// 4 + public long LicenseId { get; init; } + + /// + /// The identifiers of the Syntaxes implemented by this FilterList. + /// + /// [ 3 ] public IEnumerable SyntaxIds { get; init; } = new HashSet(); + + /// + /// The identifiers of the Languages targeted by this FilterList. + /// + /// [ 37 ] public IEnumerable LanguageIds { get; init; } = new HashSet(); + + /// + /// The identifiers of the Tags applied to this FilterList. + /// + /// [ 2 ] public IEnumerable TagIds { get; init; } = new HashSet(); + + /// + /// The view URLs. + /// public IEnumerable ViewUrls { get; init; } = new HashSet(); + + /// + /// The URL of the home page. + /// + /// https://easylist.to/ public Uri? HomeUrl { get; init; } + + /// + /// The URL of the Tor / Onion page. + /// + /// null public Uri? OnionUrl { get; init; } + + /// + /// The URL of the policy/guidelines for the types of rules this FilterList includes. + /// + /// null public Uri? PolicyUrl { get; init; } + + /// + /// The URL of the submission/contact form for adding rules to this FilterList. + /// + /// null public Uri? SubmissionUrl { get; init; } + + /// + /// The URL of the GitHub Issues page. + /// + /// https://github.com/easylist/easylist/issues public Uri? IssuesUrl { get; init; } + + /// + /// The URL of the forum page. + /// + /// https://forums.lanik.us/viewforum.php?f=23 public Uri? ForumUrl { get; init; } + + /// + /// The URL of the chat room. + /// + /// null public Uri? ChatUrl { get; init; } + + /// + /// The email address at which the project can be contacted. + /// + /// easylist@protonmail.com public string? EmailAddress { get; init; } + + /// + /// The URL at which donations to the project can be made. + /// + /// null public Uri? DonateUrl { get; init; } + + /// + /// The identifiers of the Maintainers of this FilterList. + /// + /// [ 7 ] public IEnumerable MaintainerIds { get; init; } = new HashSet(); + + /// + /// The identifiers of the FilterLists from which this FilterList was forked. + /// + /// [] public IEnumerable UpstreamFilterListIds { get; init; } = new HashSet(); + + /// + /// The identifiers of the FilterLists that have been forked from this FilterList. + /// + /// [ 166, 565 ] public IEnumerable ForkFilterListIds { get; init; } = new HashSet(); + + /// + /// The identifiers of the FilterLists that include this FilterList. + /// + /// [] public IEnumerable IncludedInFilterListIds { get; init; } = new HashSet(); + + /// + /// The identifiers of the FilterLists that this FilterList includes. + /// + /// [ 11, 13, 168 ] public IEnumerable IncludesFilterListIds { get; init; } = new HashSet(); + + /// + /// The identifiers of the FilterLists that this FilterList depends upon. + /// + /// [] public IEnumerable DependencyFilterListIds { get; init; } = new HashSet(); + + /// + /// The identifiers of the FilterLists dependent upon this FilterList. + /// + /// [] public IEnumerable DependentFilterListIds { get; init; } = new HashSet(); public record ViewUrlVm { + /// + /// The segment number of the URL for the FilterList (for multi-part lists). + /// + /// 1 public short SegmentNumber { get; init; } + + /// + /// How primary the URL is for the FilterList segment (1 is original, 2+ is a mirror; unique per SegmentNumber) + /// + /// 1 public short Primariness { get; init; } + + /// + /// The view URL. + /// + /// https://easylist.to/easylist/easylist.txt public Uri Url { get; init; } = default!; } } diff --git a/services/Directory/FilterLists.Directory.Api.Contracts/Models/ListVm.cs b/services/Directory/FilterLists.Directory.Api.Contracts/Models/ListVm.cs index 8d625261f..f36d6b365 100644 --- a/services/Directory/FilterLists.Directory.Api.Contracts/Models/ListVm.cs +++ b/services/Directory/FilterLists.Directory.Api.Contracts/Models/ListVm.cs @@ -2,13 +2,61 @@ public record ListVm { + /// + /// The identifier. + /// + /// 301 public long Id { get; init; } + + /// + /// The unique name in title case. + /// + /// EasyList public string Name { get; init; } = default!; + + /// + /// The brief description in English (preferably quoted from the project). + /// + /// + /// EasyList is the primary filter list that removes most adverts from international web pages, including unwanted + /// frames, images, and objects. It is the most popular list used by many ad blockers and forms the basis of over a + /// dozen combination and supplementary filter lists. + /// public string? Description { get; init; } - public long? LicenseId { get; init; } + + /// + /// The identifier of the License under which this FilterList is released. + /// + /// 4 + public long LicenseId { get; init; } + + /// + /// The identifiers of the Syntaxes implemented by this FilterList. + /// + /// [ 3 ] public IEnumerable SyntaxIds { get; init; } = new HashSet(); + + /// + /// The identifiers of the Languages targeted by this FilterList. + /// + /// [ 37 ] public IEnumerable LanguageIds { get; init; } = new HashSet(); + + /// + /// The identifiers of the Tags applied to this FilterList. + /// + /// [ 2 ] public IEnumerable TagIds { get; init; } = new HashSet(); + + /// + /// The primary view URL. + /// + /// https://easylist.to/easylist/easylist.txt public Uri? PrimaryViewUrl { get; init; } + + /// + /// The identifiers of the Maintainers of this FilterList. + /// + /// [ 7 ] public IEnumerable MaintainerIds { get; init; } = new HashSet(); } diff --git a/services/Directory/FilterLists.Directory.Api/Controllers/ListsController.cs b/services/Directory/FilterLists.Directory.Api/Controllers/ListsController.cs index 6464ab665..e5b7006cf 100644 --- a/services/Directory/FilterLists.Directory.Api/Controllers/ListsController.cs +++ b/services/Directory/FilterLists.Directory.Api/Controllers/ListsController.cs @@ -59,6 +59,6 @@ public async Task Create(CreateList.Command command, Cancellation [ProducesResponseType(StatusCodes.Status404NotFound)] public Task GetDetails(long id, CancellationToken cancellationToken) { - return CacheGetOrCreateAsync(() => _mediator.Send(new GetListDetails.Query(id), cancellationToken), id); + return CacheGetOrCreateAsync(() => _mediator.Send(new GetListDetails.Query { Id = id }, cancellationToken), id); } } diff --git a/services/Directory/FilterLists.Directory.Application/Commands/CreateList.cs b/services/Directory/FilterLists.Directory.Application/Commands/CreateList.cs index ce9060945..51fc53d7d 100644 --- a/services/Directory/FilterLists.Directory.Application/Commands/CreateList.cs +++ b/services/Directory/FilterLists.Directory.Application/Commands/CreateList.cs @@ -1,5 +1,4 @@ -using System.ComponentModel; -using FilterLists.Directory.Domain.Aggregates.FilterLists; +using FilterLists.Directory.Domain.Aggregates.FilterLists; using FilterLists.Directory.Domain.Aggregates.Licenses; using FilterLists.Directory.Infrastructure.Persistence.Commands.Context; using FluentValidation; @@ -10,26 +9,116 @@ namespace FilterLists.Directory.Application.Commands; public static class CreateList { - public record Command( - [property: DefaultValue("EasyList")] string Name, - IEnumerable ViewUrls, - [property: DefaultValue("EasyList is the primary filter list that removes most adverts from international web pages, including unwanted frames, images, and objects. It is the most popular list used by many ad blockers and forms the basis of over a dozen combination and supplementary filter lists.")] string? Description = default, - [property: DefaultValue(4)] long? LicenseId = default, - [property: DefaultValue("https://easylist.to/")] Uri? HomeUrl = default, - [property: DefaultValue(default(Uri))] Uri? OnionUrl = default, - [property: DefaultValue(default(Uri))] Uri? PolicyUrl = default, - [property: DefaultValue(default(Uri))] Uri? SubmissionUrl = default, - [property: DefaultValue("https://github.com/easylist/easylist/issues")] Uri? IssuesUrl = default, - [property: DefaultValue("https://forums.lanik.us/viewforum.php?f=23")] Uri? ForumUrl = default, - [property: DefaultValue(default(Uri))] Uri? ChatUrl = default, - [property: DefaultValue("easylist@protonmail.com")] string? EmailAddress = default, - [property: DefaultValue(default(Uri))] Uri? DonateUrl = default, - [property: DefaultValue("Adding EasyList because I did not see it on FilterLists.com yet.")] string? CreateReason = default) : IRequest; + public record Command : IRequest + { + /// + /// The unique name in title case. + /// + /// EasyList + public string Name { get; init; } = default!; - public record FilterListViewUrl( - [property: DefaultValue(1)] short SegmentNumber, - [property: DefaultValue(1)] short Primariness, - [property: DefaultValue("https://easylist.to/easylist/easylist.txt")] Uri Url); + /// + /// The view URLs. + /// + public IEnumerable ViewUrls { get; init; } = new HashSet(); + + /// + /// The brief description in English (preferably quoted from the project). + /// + /// + /// EasyList is the primary filter list that removes most adverts from international web pages, including unwanted + /// frames, images, and objects. It is the most popular list used by many ad blockers and forms the basis of over a + /// dozen combination and supplementary filter lists. + /// + public string? Description { get; init; } + + /// + /// The identifier of the License under which this FilterList is released. + /// + /// 4 + public long? LicenseId { get; init; } + + /// + /// The URL of the home page. + /// + /// https://easylist.to/ + public Uri? HomeUrl { get; init; } + + /// + /// The URL of the Tor / Onion page. + /// + /// null + public Uri? OnionUrl { get; init; } + + /// + /// The URL of the policy/guidelines for the types of rules this FilterList includes. + /// + /// null + public Uri? PolicyUrl { get; init; } + + /// + /// The URL of the submission/contact form for adding rules to this FilterList. + /// + /// null + public Uri? SubmissionUrl { get; init; } + + /// + /// The URL of the GitHub Issues page. + /// + /// https://github.com/easylist/easylist/issues + public Uri? IssuesUrl { get; init; } + + /// + /// The URL of the forum page. + /// + /// https://forums.lanik.us/viewforum.php?f=23 + public Uri? ForumUrl { get; init; } + + /// + /// The URL of the chat room. + /// + /// null + public Uri? ChatUrl { get; init; } + + /// + /// The email address at which the project can be contacted. + /// + /// easylist@protonmail.com + public string? EmailAddress { get; init; } + + /// + /// The URL at which donations to the project can be made. + /// + /// null + public Uri? DonateUrl { get; init; } + + /// + /// The reason that the FilterList is being added to FilterLists. + /// + /// Adding EasyList because I did not see it on FilterLists.com yet. + public string? CreateReason { get; init; } + } + + public record FilterListViewUrl + { + /// + /// The segment number of the URL for the FilterList (for multi-part lists). + /// + /// 1 + public short SegmentNumber { get; init; } + + /// + /// How primary the URL is for the FilterList segment (1 is original, 2+ is a mirror; unique per SegmentNumber) + /// + /// 1 + public short Primariness { get; init; } + + /// + /// The view URL. + /// + /// https://easylist.to/easylist/easylist.txt + public Uri Url { get; init; } = default!; + } internal class Validator : AbstractValidator { @@ -80,9 +169,21 @@ public async Task Handle(Command request, CancellationToken cancellati await _commandContext.SaveChangesAsync(cancellationToken); - return new Response(filterList.Changes.Single().Id); + return new Response + { + ChangeId = + filterList.Changes.Single() + .Id + }; } } - public record Response(long ChangeId) { } + public record Response + { + /// + /// The identifier of the Change for the new FilterList. + /// + /// 99 + public long ChangeId { get; init; } + } } diff --git a/services/Directory/FilterLists.Directory.Application/Queries/GetLanguages.cs b/services/Directory/FilterLists.Directory.Application/Queries/GetLanguages.cs index c2ebc5430..78293af74 100644 --- a/services/Directory/FilterLists.Directory.Application/Queries/GetLanguages.cs +++ b/services/Directory/FilterLists.Directory.Application/Queries/GetLanguages.cs @@ -53,13 +53,13 @@ public record LanguageVm public long Id { get; private init; } /// - /// The ISO 639-1 code. + /// The unique ISO 639-1 code. /// /// en public string Iso6391 { get; private init; } = default!; /// - /// The ISO name. + /// The unique ISO name. /// /// English public string Name { get; private init; } = default!; diff --git a/services/Directory/FilterLists.Directory.Application/Queries/GetLicenses.cs b/services/Directory/FilterLists.Directory.Application/Queries/GetLicenses.cs index f03e9de12..b2a5a6b53 100644 --- a/services/Directory/FilterLists.Directory.Application/Queries/GetLicenses.cs +++ b/services/Directory/FilterLists.Directory.Application/Queries/GetLicenses.cs @@ -51,7 +51,7 @@ public record LicenseVm public long Id { get; private init; } /// - /// The name. + /// The unique name. /// /// All Rights Reserved public string Name { get; private init; } = default!; diff --git a/services/Directory/FilterLists.Directory.Application/Queries/GetListDetails.cs b/services/Directory/FilterLists.Directory.Application/Queries/GetListDetails.cs index aa087b6b1..3766f6eae 100644 --- a/services/Directory/FilterLists.Directory.Application/Queries/GetListDetails.cs +++ b/services/Directory/FilterLists.Directory.Application/Queries/GetListDetails.cs @@ -11,14 +11,21 @@ namespace FilterLists.Directory.Application.Queries; public static class GetListDetails { - public record Query(long Id) : IRequest; + public record Query : IRequest + { + /// + /// The identifier. + /// + /// 301 + public long Id { get; init; } + } internal class Validator : AbstractValidator { public Validator() { RuleFor(q => q.Id) - .GreaterThanOrEqualTo(0); + .GreaterThan(0); } }