Move resource annotations into separate package (#1127)

* Moved resource-related attributes and (I)Identifiable to separate package

* Fixed broken links in doc-comments

* Update ROADMAP.md

Author: Bart Koelman

JsonApiDotNetCore.sln

@@ -1,6 +1,6 @@
 Microsoft Visual Studio Solution File, Format Version 12.00
-# Visual Studio Version 16
-VisualStudioVersion = 16.0.28606.126
+# Visual Studio Version 17
+VisualStudioVersion = 17.0.31919.166
 MinimumVisualStudioVersion = 10.0.40219.1
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{7A2B7ADD-ECB5-4D00-AA6A-D45BD11C97CF}"
 EndProject
@@ -48,7 +48,9 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "JsonApiDotNetCore.SourceGen
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "SourceGeneratorDebugger", "test\SourceGeneratorDebugger\SourceGeneratorDebugger.csproj", "{87D066F9-3540-4AC7-A748-134900969EE5}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SourceGeneratorTests", "test\SourceGeneratorTests\SourceGeneratorTests.csproj", "{0E0B5C51-F7E2-4F40-A4E4-DED0E9731DC9}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "SourceGeneratorTests", "test\SourceGeneratorTests\SourceGeneratorTests.csproj", "{0E0B5C51-F7E2-4F40-A4E4-DED0E9731DC9}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "JsonApiDotNetCore.Annotations", "src\JsonApiDotNetCore.Annotations\JsonApiDotNetCore.Annotations.csproj", "{83FF097C-C8C6-477B-9FAB-DF99B84978B5}"
 EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
@@ -252,6 +254,18 @@ Global
 		{0E0B5C51-F7E2-4F40-A4E4-DED0E9731DC9}.Release|x64.Build.0 = Release|Any CPU
 		{0E0B5C51-F7E2-4F40-A4E4-DED0E9731DC9}.Release|x86.ActiveCfg = Release|Any CPU
 		{0E0B5C51-F7E2-4F40-A4E4-DED0E9731DC9}.Release|x86.Build.0 = Release|Any CPU
+		{83FF097C-C8C6-477B-9FAB-DF99B84978B5}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{83FF097C-C8C6-477B-9FAB-DF99B84978B5}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{83FF097C-C8C6-477B-9FAB-DF99B84978B5}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{83FF097C-C8C6-477B-9FAB-DF99B84978B5}.Debug|x64.Build.0 = Debug|Any CPU
+		{83FF097C-C8C6-477B-9FAB-DF99B84978B5}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{83FF097C-C8C6-477B-9FAB-DF99B84978B5}.Debug|x86.Build.0 = Debug|Any CPU
+		{83FF097C-C8C6-477B-9FAB-DF99B84978B5}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{83FF097C-C8C6-477B-9FAB-DF99B84978B5}.Release|Any CPU.Build.0 = Release|Any CPU
+		{83FF097C-C8C6-477B-9FAB-DF99B84978B5}.Release|x64.ActiveCfg = Release|Any CPU
+		{83FF097C-C8C6-477B-9FAB-DF99B84978B5}.Release|x64.Build.0 = Release|Any CPU
+		{83FF097C-C8C6-477B-9FAB-DF99B84978B5}.Release|x86.ActiveCfg = Release|Any CPU
+		{83FF097C-C8C6-477B-9FAB-DF99B84978B5}.Release|x86.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -273,6 +287,7 @@ Global
 		{952C0FDE-AFC8-455C-986F-6CC882ED8953} = {7A2B7ADD-ECB5-4D00-AA6A-D45BD11C97CF}
 		{87D066F9-3540-4AC7-A748-134900969EE5} = {24B15015-62E5-42E1-9BA0-ECE6BE7AA15F}
 		{0E0B5C51-F7E2-4F40-A4E4-DED0E9731DC9} = {24B15015-62E5-42E1-9BA0-ECE6BE7AA15F}
+		{83FF097C-C8C6-477B-9FAB-DF99B84978B5} = {7A2B7ADD-ECB5-4D00-AA6A-D45BD11C97CF}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {A2421882-8F0A-4905-928F-B550B192F9A4}

ROADMAP.md

@@ -26,11 +26,11 @@ The need for breaking changes has blocked several efforts in the v4.x release, s
 - [x] Configuration validation [#170](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/170)
 - [x] Auto-generated controllers [#732](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/732) [#365](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/365)
 - [x] Support .NET 6 with EF Core 6 [#1109](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/1109)
+- [x] Extract annotations into separate package [#730](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/730)
 
 Aside from the list above, we have interest in the following topics. It's too soon yet to decide whether they'll make it into v5.x or in a later major version.
 
 - Optimistic concurrency [#1004](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/1004)
-- Extract annotations into separate package [#730](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/730)
 - OpenAPI (Swagger) [#1046](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/1046)
 - Fluent API [#776](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/776)
 - Resource inheritance [#844](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/844)

src/JsonApiDotNetCore.Annotations/.editorconfig

@@ -0,0 +1,4 @@
+[*.cs]
+
+# AV1505: Namespace should match with assembly name
+dotnet_diagnostic.AV1505.severity = none

src/JsonApiDotNetCore/ArgumentGuard.cs renamed to src/JsonApiDotNetCore.Annotations/ArgumentGuard.cs

@@ -48,27 +48,27 @@ public sealed class ResourceType
     public IReadOnlyCollection<EagerLoadAttribute> EagerLoads { get; }
 
     /// <summary>
-    /// Configures which links to show in the <see cref="Serialization.Objects.TopLevelLinks" /> object for this resource type. Defaults to
-    /// <see cref="LinkTypes.NotConfigured" />, which falls back to <see cref="IJsonApiOptions.TopLevelLinks" />.
+    /// 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>
     /// <remarks>
     /// In the process of building the resource graph, this value is set based on <see cref="ResourceLinksAttribute.TopLevelLinks" /> usage.
     /// </remarks>
     public LinkTypes TopLevelLinks { get; }
 
     /// <summary>
-    /// Configures which links to show in the <see cref="Serialization.Objects.ResourceLinks" /> object for this resource type. Defaults to
-    /// <see cref="LinkTypes.NotConfigured" />, which falls back to <see cref="IJsonApiOptions.ResourceLinks" />.
+    /// 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>
     /// <remarks>
     /// In the process of building the resource graph, this value is set based on <see cref="ResourceLinksAttribute.ResourceLinks" /> usage.
     /// </remarks>
     public LinkTypes ResourceLinks { get; }
 
     /// <summary>
-    /// Configures which links to show in the <see cref="Serialization.Objects.RelationshipLinks" /> object for all relationships of this resource type.
-    /// Defaults to <see cref="LinkTypes.NotConfigured" />, which falls back to <see cref="IJsonApiOptions.RelationshipLinks" />. This can be overruled per
-    /// relationship by setting <see cref="RelationshipAttribute.Links" />.
+    /// 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>
     /// <remarks>
     /// In the process of building the resource graph, this value is set based on <see cref="ResourceLinksAttribute.RelationshipLinks" /> usage.

src/JsonApiDotNetCore/CollectionConverter.cs renamed to src/JsonApiDotNetCore.Annotations/CollectionConverter.cs

@@ -0,0 +1,30 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>$(TargetFrameworkName)</TargetFramework>
+    <IsPackable>true</IsPackable>
+    <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
+    <RootNamespace>JsonApiDotNetCore</RootNamespace>
+  </PropertyGroup>
+
+  <PropertyGroup>
+    <VersionPrefix>$(JsonApiDotNetCoreVersionPrefix)</VersionPrefix>
+    <PackageTags>jsonapidotnetcore;jsonapi;json:api;dotnet;asp.net;rest;web-api</PackageTags>
+    <Description>Annotations for JsonApiDotNetCore, a framework for building JSON:API compliant REST APIs using ASP.NET and Entity Framework Core.</Description>
+    <Authors>json-api-dotnet</Authors>
+    <PackageProjectUrl>https://www.jsonapi.net/</PackageProjectUrl>
+    <PackageLicenseExpression>MIT</PackageLicenseExpression>
+    <PackageRequireLicenseAcceptance>false</PackageRequireLicenseAcceptance>
+    <PackageReleaseNotes>See https://github.com/json-api-dotnet/JsonApiDotNetCore/releases.</PackageReleaseNotes>
+    <PackageIcon>logo.png</PackageIcon>
+    <PublishRepositoryUrl>true</PublishRepositoryUrl>
+    <EmbedUntrackedSources>true</EmbedUntrackedSources>
+    <DebugType>embedded</DebugType>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <None Include="..\..\logo.png" Visible="false">
+      <Pack>True</Pack>
+      <PackagePath></PackagePath>
+    </None>
+  </ItemGroup>
+</Project>

src/JsonApiDotNetCore/Configuration/ResourceType.cs renamed to src/JsonApiDotNetCore.Annotations/Configuration/ResourceType.cs

@@ -0,0 +1,7 @@
+using System.Runtime.CompilerServices;
+
+[assembly: InternalsVisibleTo("Benchmarks")]
+[assembly: InternalsVisibleTo("JsonApiDotNetCore")]
+[assembly: InternalsVisibleTo("JsonApiDotNetCoreTests")]
+[assembly: InternalsVisibleTo("UnitTests")]
+[assembly: InternalsVisibleTo("TestBuildingBlocks")]

src/JsonApiDotNetCore/Controllers/JsonApiEndpoints.cs renamed to src/JsonApiDotNetCore.Annotations/Controllers/JsonApiEndpoints.cs

@@ -63,9 +63,8 @@ public abstract class RelationshipAttribute : ResourceFieldAttribute
     public ResourceType RightType { get; internal set; } = null!;
 
     /// <summary>
-    /// Configures which links to show in the <see cref="Serialization.Objects.RelationshipLinks" /> object for this relationship. Defaults to
-    /// <see cref="LinkTypes.NotConfigured" />, which falls back to <see cref="ResourceLinksAttribute.RelationshipLinks" /> and then falls back to
-    /// <see cref="IJsonApiOptions.RelationshipLinks" />.
+    /// 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;
 

src/JsonApiDotNetCore.Annotations/JsonApiDotNetCore.Annotations.csproj

@@ -0,0 +1,30 @@
+using JetBrains.Annotations;
+
+namespace JsonApiDotNetCore.Resources.Annotations;
+
+/// <summary>
+/// When put on a resource class, overrides global configuration for which links to render.
+/// </summary>
+[PublicAPI]
+[AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct)]
+public sealed class ResourceLinksAttribute : Attribute
+{
+    /// <summary>
+    /// 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;
+
+    /// <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;
+
+    /// <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;
+}

src/JsonApiDotNetCore/ObjectExtensions.cs renamed to src/JsonApiDotNetCore.Annotations/ObjectExtensions.cs

@@ -63,19 +63,19 @@ public interface IJsonApiOptions
     bool UseRelativeLinks { get; }
 
     /// <summary>
-    /// Configures which links to show in the <see cref="Serialization.Objects.TopLevelLinks" /> object. Defaults to <see cref="LinkTypes.All" />. This
+    /// Configures which links to write in the <see cref="Serialization.Objects.TopLevelLinks" /> object. Defaults to <see cref="LinkTypes.All" />. This
     /// setting can be overruled per resource type by adding <see cref="ResourceLinksAttribute" /> on the class definition of a resource.
     /// </summary>
     LinkTypes TopLevelLinks { get; }
 
     /// <summary>
-    /// Configures which links to show in the <see cref="Serialization.Objects.ResourceLinks" /> object. Defaults to <see cref="LinkTypes.All" />. This
+    /// Configures which links to write in the <see cref="Serialization.Objects.ResourceLinks" /> object. Defaults to <see cref="LinkTypes.All" />. This
     /// setting can be overruled per resource type by adding <see cref="ResourceLinksAttribute" /> on the class definition of a resource.
     /// </summary>
     LinkTypes ResourceLinks { get; }
 
     /// <summary>
-    /// Configures which links to show in the <see cref="Serialization.Objects.RelationshipLinks" /> object. Defaults to <see cref="LinkTypes.All" />. This
+    /// Configures which links to write in the <see cref="Serialization.Objects.RelationshipLinks" /> object. Defaults to <see cref="LinkTypes.All" />. This
     /// setting can be overruled for all relationships per resource type by adding <see cref="ResourceLinksAttribute" /> on the class definition of a
     /// resource. This can be further overruled per relationship by setting <see cref="RelationshipAttribute.Links" />.
     /// </summary>

src/JsonApiDotNetCore.Annotations/Properties/AssemblyInfo.cs

@@ -28,6 +28,7 @@
   </ItemGroup>
 
   <ItemGroup>
+    <ProjectReference Include="..\JsonApiDotNetCore.Annotations\JsonApiDotNetCore.Annotations.csproj" />
     <ProjectReference Include="..\JsonApiDotNetCore.SourceGenerators\JsonApiDotNetCore.SourceGenerators.csproj" IncludeAssets="analyzers" />
   </ItemGroup>
 

src/JsonApiDotNetCore/Resources/Annotations/AttrAttribute.cs renamed to src/JsonApiDotNetCore.Annotations/Resources/Annotations/AttrAttribute.cs

@@ -13,8 +13,8 @@
   </ItemGroup>
 
   <ItemGroup>
-    <Compile Include="..\..\src\JsonApiDotNetCore\Controllers\JsonApiEndpoints.cs" Link="JsonApiDotNetCore\JsonApiEndpoints.cs" />
-    <Compile Include="..\..\src\JsonApiDotNetCore\Resources\Annotations\ResourceAttribute.cs" Link="JsonApiDotNetCore\ResourceAttribute.cs" />
+    <Compile Include="..\..\src\JsonApiDotNetCore.Annotations\Controllers\JsonApiEndpoints.cs" Link="JsonApiDotNetCore\JsonApiEndpoints.cs" />
+    <Compile Include="..\..\src\JsonApiDotNetCore.Annotations\Resources\Annotations\ResourceAttribute.cs" Link="JsonApiDotNetCore\ResourceAttribute.cs" />
   </ItemGroup>
 
   <ItemGroup>

src/JsonApiDotNetCore/Resources/Annotations/AttrCapabilities.cs renamed to src/JsonApiDotNetCore.Annotations/Resources/Annotations/AttrCapabilities.cs

@@ -1,3 +1,4 @@
+using JsonApiDotNetCore.Controllers;
 using JsonApiDotNetCore.Resources.Annotations;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.CodeAnalysis;
@@ -58,7 +59,8 @@ public CompilationBuilder WithJsonApiDotNetCoreReferences()
         foreach (PortableExecutableReference reference in new[]
         {
             MetadataReference.CreateFromFile(typeof(ControllerBase).Assembly.Location),
-            MetadataReference.CreateFromFile(typeof(AttrAttribute).Assembly.Location)
+            MetadataReference.CreateFromFile(typeof(AttrAttribute).Assembly.Location),
+            MetadataReference.CreateFromFile(typeof(JsonApiController<,>).Assembly.Location)
         })
         {
             _references.Add(reference);