Add support for configuring the visibility of the "describedby" link

src/JsonApiDotNetCore.Annotations/Resources/Annotations/LinkTypes.shared.cs

@@ -3,10 +3,11 @@ namespace JsonApiDotNetCore.Resources.Annotations;
 [Flags]
 public enum LinkTypes
 {
-    Self = 1 << 0,
-    Related = 1 << 1,
-    Pagination = 1 << 2,
-    NotConfigured = 1 << 3,
-    None = 1 << 4,
-    All = Self | Related | Pagination
+    NotConfigured = 0,
+    None = 1 << 0,
+    Self = 1 << 1,
+    Related = 1 << 2,
+    DescribedBy = 1 << 3,
+    Pagination = 1 << 4,
+    All = Self | Related | DescribedBy | Pagination
 }

src/JsonApiDotNetCore.Annotations/Resources/Annotations/RelationshipAttribute.cs

@@ -70,7 +70,7 @@ internal set
     /// Configures which links to write in the relationship-level links object for this relationship. Defaults to <see cref="LinkTypes.NotConfigured" />,
     /// which falls back to <see cref="ResourceLinksAttribute.RelationshipLinks" /> and then falls back to RelationshipLinks in global options.
     /// </summary>
-    public LinkTypes Links { get; set; } = LinkTypes.NotConfigured;
+    public LinkTypes Links { get; set; }
 
     /// <summary>
     /// Whether or not this relationship can be included using the <c>include</c> query string parameter. This is <c>true</c> by default.

src/JsonApiDotNetCore.Annotations/Resources/Annotations/RelationshipAttribute.netstandard.cs

@@ -9,7 +9,7 @@ namespace JsonApiDotNetCore.Resources.Annotations;
 public abstract class RelationshipAttribute : ResourceFieldAttribute
 {
     /// <summary />
-    public LinkTypes Links { get; set; } = LinkTypes.NotConfigured;
+    public LinkTypes Links { get; set; }
 
     /// <summary />
     [Obsolete("Use AllowInclude in Capabilities instead.")]

src/JsonApiDotNetCore.Annotations/Resources/Annotations/ResourceLinksAttribute.shared.cs

@@ -13,18 +13,18 @@ public sealed class ResourceLinksAttribute : Attribute
     /// Configures which links to write in the top-level links object for this resource type. Defaults to <see cref="LinkTypes.NotConfigured" />, which falls
     /// back to TopLevelLinks in global options.
     /// </summary>
-    public LinkTypes TopLevelLinks { get; set; } = LinkTypes.NotConfigured;
+    public LinkTypes TopLevelLinks { get; set; }
 
     /// <summary>
     /// Configures which links to write in the resource-level links object for this resource type. Defaults to <see cref="LinkTypes.NotConfigured" />, which
     /// falls back to ResourceLinks in global options.
     /// </summary>
-    public LinkTypes ResourceLinks { get; set; } = LinkTypes.NotConfigured;
+    public LinkTypes ResourceLinks { get; set; }
 
     /// <summary>
     /// Configures which links to write in the relationship-level links object for all relationships of this resource type. Defaults to
     /// <see cref="LinkTypes.NotConfigured" />, which falls back to RelationshipLinks in global options. This can be overruled per relationship by setting
     /// <see cref="RelationshipAttribute.Links" />.
     /// </summary>
-    public LinkTypes RelationshipLinks { get; set; } = LinkTypes.NotConfigured;
+    public LinkTypes RelationshipLinks { get; set; }
 }

src/JsonApiDotNetCore/Serialization/Response/LinkBuilder.cs

@@ -100,12 +100,15 @@ private static string NoAsyncSuffix(string actionName)
             SetPaginationInTopLevelLinks(resourceType!, links);
         }
 
-        string? documentDescriptionUrl = _documentDescriptionLinkProvider.GetUrl();
-
-        if (!string.IsNullOrEmpty(documentDescriptionUrl))
+        if (ShouldIncludeTopLevelLink(LinkTypes.DescribedBy, resourceType))
         {
-            var requestUri = new Uri(HttpContext.Request.GetEncodedUrl());
-            links.DescribedBy = UriNormalizer.Normalize(documentDescriptionUrl, _options.UseRelativeLinks, requestUri);
+            string? documentDescriptionUrl = _documentDescriptionLinkProvider.GetUrl();
+
+            if (!string.IsNullOrEmpty(documentDescriptionUrl))
+            {
+                var requestUri = new Uri(HttpContext.Request.GetEncodedUrl());
+                links.DescribedBy = UriNormalizer.Normalize(documentDescriptionUrl, _options.UseRelativeLinks, requestUri);
+            }
         }
 
         return links.HasValue() ? links : null;

test/JsonApiDotNetCoreTests/UnitTests/Links/LinkInclusionTests.cs

@@ -22,36 +22,49 @@ public sealed class LinkInclusionTests
     [InlineData(LinkTypes.NotConfigured, LinkTypes.None, LinkTypes.None)]
     [InlineData(LinkTypes.NotConfigured, LinkTypes.Self, LinkTypes.Self)]
     [InlineData(LinkTypes.NotConfigured, LinkTypes.Related, LinkTypes.Related)]
+    [InlineData(LinkTypes.NotConfigured, LinkTypes.DescribedBy, LinkTypes.DescribedBy)]
     [InlineData(LinkTypes.NotConfigured, LinkTypes.Pagination, LinkTypes.Pagination)]
     [InlineData(LinkTypes.NotConfigured, LinkTypes.All, LinkTypes.All)]
     [InlineData(LinkTypes.None, LinkTypes.NotConfigured, LinkTypes.None)]
     [InlineData(LinkTypes.None, LinkTypes.None, LinkTypes.None)]
     [InlineData(LinkTypes.None, LinkTypes.Self, LinkTypes.None)]
     [InlineData(LinkTypes.None, LinkTypes.Related, LinkTypes.None)]
+    [InlineData(LinkTypes.None, LinkTypes.DescribedBy, LinkTypes.None)]
     [InlineData(LinkTypes.None, LinkTypes.Pagination, LinkTypes.None)]
     [InlineData(LinkTypes.None, LinkTypes.All, LinkTypes.None)]
     [InlineData(LinkTypes.Self, LinkTypes.NotConfigured, LinkTypes.Self)]
     [InlineData(LinkTypes.Self, LinkTypes.None, LinkTypes.Self)]
     [InlineData(LinkTypes.Self, LinkTypes.Self, LinkTypes.Self)]
     [InlineData(LinkTypes.Self, LinkTypes.Related, LinkTypes.Self)]
+    [InlineData(LinkTypes.Self, LinkTypes.DescribedBy, LinkTypes.Self)]
     [InlineData(LinkTypes.Self, LinkTypes.Pagination, LinkTypes.Self)]
     [InlineData(LinkTypes.Self, LinkTypes.All, LinkTypes.Self)]
     [InlineData(LinkTypes.Related, LinkTypes.NotConfigured, LinkTypes.Related)]
     [InlineData(LinkTypes.Related, LinkTypes.None, LinkTypes.Related)]
     [InlineData(LinkTypes.Related, LinkTypes.Self, LinkTypes.Related)]
     [InlineData(LinkTypes.Related, LinkTypes.Related, LinkTypes.Related)]
+    [InlineData(LinkTypes.Related, LinkTypes.DescribedBy, LinkTypes.Related)]
     [InlineData(LinkTypes.Related, LinkTypes.Pagination, LinkTypes.Related)]
     [InlineData(LinkTypes.Related, LinkTypes.All, LinkTypes.Related)]
+    [InlineData(LinkTypes.DescribedBy, LinkTypes.NotConfigured, LinkTypes.DescribedBy)]
+    [InlineData(LinkTypes.DescribedBy, LinkTypes.None, LinkTypes.DescribedBy)]
+    [InlineData(LinkTypes.DescribedBy, LinkTypes.Self, LinkTypes.DescribedBy)]
+    [InlineData(LinkTypes.DescribedBy, LinkTypes.Related, LinkTypes.DescribedBy)]
+    [InlineData(LinkTypes.DescribedBy, LinkTypes.DescribedBy, LinkTypes.DescribedBy)]
+    [InlineData(LinkTypes.DescribedBy, LinkTypes.Pagination, LinkTypes.DescribedBy)]
+    [InlineData(LinkTypes.DescribedBy, LinkTypes.All, LinkTypes.DescribedBy)]
     [InlineData(LinkTypes.Pagination, LinkTypes.NotConfigured, LinkTypes.Pagination)]
     [InlineData(LinkTypes.Pagination, LinkTypes.None, LinkTypes.Pagination)]
     [InlineData(LinkTypes.Pagination, LinkTypes.Self, LinkTypes.Pagination)]
     [InlineData(LinkTypes.Pagination, LinkTypes.Related, LinkTypes.Pagination)]
+    [InlineData(LinkTypes.Pagination, LinkTypes.DescribedBy, LinkTypes.Pagination)]
     [InlineData(LinkTypes.Pagination, LinkTypes.Pagination, LinkTypes.Pagination)]
     [InlineData(LinkTypes.Pagination, LinkTypes.All, LinkTypes.Pagination)]
     [InlineData(LinkTypes.All, LinkTypes.NotConfigured, LinkTypes.All)]
     [InlineData(LinkTypes.All, LinkTypes.None, LinkTypes.All)]
     [InlineData(LinkTypes.All, LinkTypes.Self, LinkTypes.All)]
     [InlineData(LinkTypes.All, LinkTypes.Related, LinkTypes.All)]
+    [InlineData(LinkTypes.All, LinkTypes.DescribedBy, LinkTypes.All)]
     [InlineData(LinkTypes.All, LinkTypes.Pagination, LinkTypes.All)]
     [InlineData(LinkTypes.All, LinkTypes.All, LinkTypes.All)]
     public void Applies_cascading_settings_for_top_level_links(LinkTypes linksInResourceType, LinkTypes linksInOptions, LinkTypes expected)
@@ -88,7 +101,7 @@ public void Applies_cascading_settings_for_top_level_links(LinkTypes linksInReso
         var linkGenerator = new FakeLinkGenerator();
         var controllerResourceMapping = new FakeControllerResourceMapping();
         var paginationParser = new PaginationParser();
-        var documentDescriptionLinkProvider = new NoDocumentDescriptionLinkProvider();
+        var documentDescriptionLinkProvider = new NonEmptyDocumentDescriptionLinkProvider();
 
         var linkBuilder = new LinkBuilder(options, request, paginationContext, httpContextAccessor, linkGenerator, controllerResourceMapping, paginationParser,
             documentDescriptionLinkProvider);
@@ -435,4 +448,12 @@ public override string GetUriByAddress<TAddress>(TAddress address, RouteValueDic
             throw new NotImplementedException();
         }
     }
+
+    private sealed class NonEmptyDocumentDescriptionLinkProvider : IDocumentDescriptionLinkProvider
+    {
+        public string GetUrl()
+        {
+            return "openapi.yaml";
+        }
+    }
 }