Merge master into openapi

.config/dotnet-tools.json

@@ -15,7 +15,7 @@
       ]
     },
     "dotnet-reportgenerator-globaltool": {
-      "version": "5.2.3",
+      "version": "5.2.4",
       "commands": [
         "reportgenerator"
       ]

docs/usage/extensibility/controllers.md

@@ -2,6 +2,8 @@
 
 To expose API endpoints, ASP.NET controllers need to be defined.
 
+## Auto-generated controllers
+
 _since v5_
 
 Controllers are auto-generated (using [source generators](https://docs.microsoft.com/en-us/dotnet/csharp/roslyn-sdk/source-generators-overview)) when you add `[Resource]` on your model class:
@@ -14,7 +16,12 @@ public class Article : Identifiable<Guid>
 }
 ```
 
-## Resource Access Control
+> [!NOTE]
+> Auto-generated controllers are convenient to get started, but may not work as expected with certain customizations.
+> For example, when model classes are defined in a separate project, the controllers are generated in that project as well, which is probably not what you want.
+> In such cases, it's perfectly fine to use [explicit controllers](#explicit-controllers) instead.
+
+### Resource Access Control
 
 It is often desirable to limit which endpoints are exposed on your controller.
 A subset can be specified too:
@@ -52,7 +59,7 @@ DELETE http://localhost:14140/articles/1 HTTP/1.1
 }
 ```
 
-## Augmenting controllers
+### Augmenting controllers
 
 Auto-generated controllers can easily be augmented because they are partial classes. For example:
 
@@ -91,9 +98,9 @@ partial class ArticlesController
 In case you don't want to use auto-generated controllers and define them yourself (see below), remove
 `[Resource]` from your models or use `[Resource(GenerateControllerEndpoints = JsonApiEndpoints.None)]`.
 
-## Earlier versions
+## Explicit controllers
 
-In earlier versions of JsonApiDotNetCore, you needed to create controllers that inherit from `JsonApiController<TResource, TId>`. For example:
+To define your own controller class, inherit from `JsonApiController<TResource, TId>`. For example:
 
 ```c#
 public class ArticlesController : JsonApiController<Article, Guid>

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";
+        }
+    }
 }