Merge master into openapi

.config/dotnet-tools.json

@@ -3,7 +3,7 @@
   "isRoot": true,
   "tools": {
     "jetbrains.resharper.globaltools": {
-      "version": "2024.3.3",
+      "version": "2024.3.5",
       "commands": [
         "jb"
       ],
@@ -17,7 +17,7 @@
       "rollForward": false
     },
     "dotnet-reportgenerator-globaltool": {
-      "version": "5.4.3",
+      "version": "5.4.4",
       "commands": [
         "reportgenerator"
       ],

.github/workflows/build.yml

@@ -45,9 +45,10 @@ jobs:
     - name: Setup .NET
       uses: actions/setup-dotnet@v4
       with:
+        # Block buggy release from February 11, 2025
         dotnet-version: |
-          8.0.x
-          9.0.x
+          8.0.309 
+          9.0.103
     - name: Show installed versions
       shell: pwsh
       run: |
@@ -132,7 +133,7 @@ jobs:
       run: |
         cd docs
         & ./generate-examples.ps1
-        dotnet docfx docfx.json
+        dotnet docfx docfx.json --warningsAsErrors true
         if ($LastExitCode -ne 0) {
             Write-Error "docfx failed with exit code $LastExitCode."
         }
@@ -163,9 +164,10 @@ jobs:
     - name: Setup .NET
       uses: actions/setup-dotnet@v4
       with:
+        # Block buggy release from February 11, 2025
         dotnet-version: |
-          8.0.x
-          9.0.x
+          8.0.309 
+          9.0.103
     - name: Git checkout
       uses: actions/checkout@v4
     - name: Restore tools
@@ -218,9 +220,10 @@ jobs:
     - name: Setup .NET
       uses: actions/setup-dotnet@v4
       with:
+        # Block buggy release from February 11, 2025
         dotnet-version: |
-          8.0.x
-          9.0.x
+          8.0.309 
+          9.0.103
     - name: Git checkout
       uses: actions/checkout@v4
       with:

.github/workflows/codeql.yml

@@ -26,9 +26,10 @@ jobs:
     - name: Setup .NET
       uses: actions/setup-dotnet@v4
       with:
+        # Block buggy release from February 11, 2025
         dotnet-version: |
-          8.0.x
-          9.0.x
+          8.0.309 
+          9.0.103
     - name: Git checkout
       uses: actions/checkout@v4
     - name: Initialize CodeQL

docs/build-dev.ps1

@@ -40,7 +40,7 @@ if (-Not $NoBuild -Or -Not (Test-Path -Path _site)) {
 dotnet tool restore
 VerifySuccessExitCode
 
-dotnet docfx ./docfx.json
+dotnet docfx ./docfx.json --warningsAsErrors true
 VerifySuccessExitCode
 
 Copy-Item -Force home/*.html _site/

docs/docfx.json

@@ -1,53 +1,67 @@
 {
-    "metadata": [
+  "metadata": [
+    {
+      "properties": {
+        "ProduceReferenceAssembly": "true"
+      },
+      "src": [
         {
-            "src": [
-                {
-                    "files": [ "**/JsonApiDotNetCore.csproj","**/JsonApiDotNetCore.Annotations.csproj" ],
-                    "src": "../"
-                }
-            ],
-            "dest": "api",
-            "disableGitFeatures": false
+          "files": [
+            "**/JsonApiDotNetCore.csproj",
+            "**/JsonApiDotNetCore.Annotations.csproj"
+          ],
+          "src": "../"
         }
-    ],
-    "build": {
-        "content": [
-            {
-                "files": [
-                    "api/**.yml",
-                    "api/index.md",
-                    "getting-started/**.md",
-                    "getting-started/**/toc.yml",
-                    "usage/**.md",
-                    "request-examples/**.md",
-                    "internals/**.md",
-                    "toc.yml",
-                    "*.md"
-                ],
-                "exclude": [
-                    "**/README.md"
-                ]
-            }
-        ],
-        "resource": [
-            {
-                "files": [ "diagrams/*.svg" ]
-            }
-        ],
-        "overwrite": [
-            {
-                "exclude": [ "obj/**", "_site/**" ]
-            }
-        ],
-        "dest": "_site",
-        "globalMetadataFiles": [],
-        "fileMetadataFiles": [],
-        "template": [ "default", "modern" ],
-        "postProcessors": [],
-        "noLangKeyword": false,
-        "keepFileLink": false,
-        "cleanupCacheHistory": false,
-        "disableGitFeatures": false
+      ],
+      "dest": "api",
+      "disableGitFeatures": false
     }
+  ],
+  "build": {
+    "content": [
+      {
+        "files": [
+          "api/**.yml",
+          "api/index.md",
+          "getting-started/**.md",
+          "getting-started/**/toc.yml",
+          "usage/**.md",
+          "request-examples/**.md",
+          "internals/**.md",
+          "toc.yml",
+          "*.md"
+        ],
+        "exclude": [
+          "**/README.md"
+        ]
+      }
+    ],
+    "resource": [
+      {
+        "files": [
+          "diagrams/*.svg"
+        ]
+      }
+    ],
+    "overwrite": [
+      {
+        "exclude": [
+          "obj/**",
+          "_site/**"
+        ]
+      }
+    ],
+    "dest": "_site",
+    "globalMetadataFiles": [],
+    "fileMetadataFiles": [],
+    "template": [
+      "default",
+      "modern"
+    ],
+    "postProcessors": [],
+    "noLangKeyword": false,
+    "keepFileLink": false,
+    "cleanupCacheHistory": false,
+    "disableGitFeatures": false
+  }
 }

docs/usage/common-pitfalls.md

@@ -50,7 +50,7 @@ Did you notice the missing type of the `LoginAccount.Customer` property? We must
 This is only one of the issues you'll run into. Just don't go there.
 
 The right way to model this is by having only `Customer` instead of `WebCustomer` and `AdminCustomer`. And then:
-- Hide the `CreditRating` property for web users using [this](https://www.jsonapi.net/usage/extensibility/resource-definitions.html#excluding-fields) approach.
+- Hide the `CreditRating` property for web users using [this](~/usage/extensibility/resource-definitions.md#excluding-fields) approach.
 - Block web users from setting the `CreditRating` property from POST/PATCH resource endpoints by either:
   - Detecting if the `CreditRating` property has changed, such as done [here](https://github.com/json-api-dotnet/JsonApiDotNetCore/blob/master/test/JsonApiDotNetCoreTests/IntegrationTests/InputValidation/RequestBody/WorkflowDefinition.cs).
   - Injecting `ITargetedFields`, throwing an error when it contains the `CreditRating` property.
@@ -87,6 +87,11 @@ Neither sounds very compelling. If stored procedures is what you need, you're be
 Although recommended by Microsoft for hard-written controllers, the opinionated behavior of [`[ApiController]`](https://learn.microsoft.com/en-us/aspnet/core/web-api/?view=aspnetcore-7.0#apicontroller-attribute) violates the JSON:API specification.
 Despite JsonApiDotNetCore trying its best to deal with it, the experience won't be as good as leaving it out.
 
+#### Don't use auto-generated controllers with shared models
+
+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.
+For details, see [here](~/usage/extensibility/controllers.md#auto-generated-controllers).
+
 #### Register/override injectable services
 Register your JSON:API resource services, resource definitions and repositories with `services.AddResourceService/AddResourceDefinition/AddResourceRepository()` instead of `services.AddScoped()`.
 When using [Auto-discovery](~/usage/resource-graph.md#auto-discovery), you don't need to register these at all.

package-versions.props

@@ -23,7 +23,6 @@
     <NSwagApiClientVersion>14.2.*</NSwagApiClientVersion>
     <NewtonsoftJsonVersion>13.0.*</NewtonsoftJsonVersion>
     <ScalarAspNetCoreVersion>1.2.*</ScalarAspNetCoreVersion>
-    <SourceLinkVersion>8.0.*</SourceLinkVersion>
     <SwashbuckleVersion>7.*-*</SwashbuckleVersion>
     <SystemTextJsonVersion>9.0.*</SystemTextJsonVersion>
     <TestSdkVersion>17.12.*</TestSdkVersion>

src/JsonApiDotNetCore.Annotations/JsonApiDotNetCore.Annotations.csproj

@@ -20,7 +20,6 @@
     <PackageIcon>package-icon.png</PackageIcon>
     <PackageReadmeFile>PackageReadme.md</PackageReadmeFile>
     <PublishRepositoryUrl>true</PublishRepositoryUrl>
-    <EmbedUntrackedSources>true</EmbedUntrackedSources>
     <DebugType>embedded</DebugType>
   </PropertyGroup>
 
@@ -47,7 +46,6 @@
   </ItemGroup>
 
   <ItemGroup>
-    <PackageReference Include="Microsoft.SourceLink.GitHub" Version="$(SourceLinkVersion)" PrivateAssets="All" />
     <PackageReference Include="SauceControl.InheritDoc" Version="$(InheritDocVersion)" PrivateAssets="All" />
   </ItemGroup>
 </Project>

src/JsonApiDotNetCore.OpenApi.Client.Kiota/JsonApiDotNetCore.OpenApi.Client.Kiota.csproj

@@ -21,7 +21,6 @@
     <PackageIcon>package-icon.png</PackageIcon>
     <PackageReadmeFile>PackageReadme.md</PackageReadmeFile>
     <PublishRepositoryUrl>true</PublishRepositoryUrl>
-    <EmbedUntrackedSources>true</EmbedUntrackedSources>
     <DebugType>embedded</DebugType>
   </PropertyGroup>
 
@@ -39,7 +38,6 @@
   </ItemGroup>
 
   <ItemGroup>
-    <PackageReference Include="Microsoft.SourceLink.GitHub" Version="$(SourceLinkVersion)" PrivateAssets="All" />
     <PackageReference Include="SauceControl.InheritDoc" Version="$(InheritDocVersion)" PrivateAssets="All" />
   </ItemGroup>
 </Project>

src/JsonApiDotNetCore.OpenApi.Client.NSwag/JsonApiDotNetCore.OpenApi.Client.NSwag.csproj

@@ -20,7 +20,6 @@
     <PackageIcon>package-icon.png</PackageIcon>
     <PackageReadmeFile>PackageReadme.md</PackageReadmeFile>
     <PublishRepositoryUrl>true</PublishRepositoryUrl>
-    <EmbedUntrackedSources>true</EmbedUntrackedSources>
     <DebugType>embedded</DebugType>
   </PropertyGroup>
 
@@ -31,7 +30,6 @@
   </ItemGroup>
 
   <ItemGroup>
-    <PackageReference Include="Microsoft.SourceLink.GitHub" Version="$(SourceLinkVersion)" PrivateAssets="All" />
     <PackageReference Include="Newtonsoft.Json" Version="$(NewtonsoftJsonFrozenVersion)" />
     <PackageReference Include="SauceControl.InheritDoc" Version="$(InheritDocVersion)" PrivateAssets="All" />
   </ItemGroup>

src/JsonApiDotNetCore.OpenApi.Swashbuckle/JsonApiDotNetCore.OpenApi.Swashbuckle.csproj

@@ -20,7 +20,6 @@
     <PackageIcon>package-icon.png</PackageIcon>
     <PackageReadmeFile>PackageReadme.md</PackageReadmeFile>
     <PublishRepositoryUrl>true</PublishRepositoryUrl>
-    <EmbedUntrackedSources>true</EmbedUntrackedSources>
     <DebugType>embedded</DebugType>
   </PropertyGroup>
 
@@ -34,7 +33,6 @@
   </ItemGroup>
 
   <ItemGroup>
-    <PackageReference Include="Microsoft.SourceLink.GitHub" Version="$(SourceLinkVersion)" PrivateAssets="All" />
     <PackageReference Include="SauceControl.InheritDoc" Version="$(InheritDocVersion)" PrivateAssets="All" />
     <PackageReference Include="Swashbuckle.AspNetCore" Version="$(SwashbuckleFrozenVersion)" />
   </ItemGroup>

src/JsonApiDotNetCore/JsonApiDotNetCore.csproj

@@ -19,7 +19,6 @@
     <PackageIcon>package-icon.png</PackageIcon>
     <PackageReadmeFile>PackageReadme.md</PackageReadmeFile>
     <PublishRepositoryUrl>true</PublishRepositoryUrl>
-    <EmbedUntrackedSources>true</EmbedUntrackedSources>
     <DebugType>embedded</DebugType>
   </PropertyGroup>
 
@@ -42,7 +41,6 @@
     <PackageReference Include="Humanizer.Core" Version="$(HumanizerFrozenVersion)" />
     <PackageReference Include="Microsoft.EntityFrameworkCore" Version="$(EntityFrameworkCoreFrozenVersion)" />
     <PackageReference Include="Microsoft.EntityFrameworkCore.Relational" Version="$(EntityFrameworkCoreFrozenVersion)" />
-    <PackageReference Include="Microsoft.SourceLink.GitHub" Version="$(SourceLinkVersion)" PrivateAssets="All" />
     <PackageReference Include="SauceControl.InheritDoc" Version="$(InheritDocVersion)" PrivateAssets="All" />
   </ItemGroup>
 </Project>