From 5f907fb08b7eff696de843ef04417fe9379fce9a Mon Sep 17 00:00:00 2001
From: bkoelman <bkoelman@users.noreply.github.com>
Date: Sat, 23 Mar 2024 10:15:13 +0000
Subject: [PATCH] Auto-generated documentation from
 55408c90fd07538e564fc5286c3e03f6e70d12ae

---
 usage/extensibility/controllers.html | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/usage/extensibility/controllers.html b/usage/extensibility/controllers.html
index 74ab1a6585..2e45325016 100644
--- a/usage/extensibility/controllers.html
+++ b/usage/extensibility/controllers.html
@@ -83,6 +83,7 @@ <h5 class="offcanvas-title" id="tocOffcanvasLabel">Table of Contents</h5>
 <h1 id="controllers">Controllers</h1>
 
 <p>To expose API endpoints, ASP.NET controllers need to be defined.</p>
+<h2 id="auto-generated-controllers">Auto-generated controllers</h2>
 <p><em>since v5</em></p>
 <p>Controllers are auto-generated (using <a href="https://docs.microsoft.com/en-us/dotnet/csharp/roslyn-sdk/source-generators-overview">source generators</a>) when you add <code>[Resource]</code> on your model class:</p>
 <pre><code class="lang-c#">[Resource] // Generates ArticlesController.g.cs
@@ -91,7 +92,13 @@ <h1 id="controllers">Controllers</h1>
     // ...
 }
 </code></pre>
-<h2 id="resource-access-control">Resource Access Control</h2>
+<div class="NOTE">
+<h5>Note</h5>
+<p>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 <a href="#explicit-controllers">explicit controllers</a> instead.</p>
+</div>
+<h3 id="resource-access-control">Resource Access Control</h3>
 <p>It is often desirable to limit which endpoints are exposed on your controller.
 A subset can be specified too:</p>
 <pre><code class="lang-c#">[Resource(GenerateControllerEndpoints =
@@ -119,7 +126,7 @@ <h2 id="resource-access-control">Resource Access Control</h2>
   ]
 }
 </code></pre>
-<h2 id="augmenting-controllers">Augmenting controllers</h2>
+<h3 id="augmenting-controllers">Augmenting controllers</h3>
 <p>Auto-generated controllers can easily be augmented because they are partial classes. For example:</p>
 <pre><code class="lang-c#">[DisableRoutingConvention]
 [Route(&quot;some/custom/route&quot;)]
@@ -150,8 +157,8 @@ <h2 id="augmenting-controllers">Augmenting controllers</h2>
 </code></pre>
 <p>In case you don't want to use auto-generated controllers and define them yourself (see below), remove
 <code>[Resource]</code> from your models or use <code>[Resource(GenerateControllerEndpoints = JsonApiEndpoints.None)]</code>.</p>
-<h2 id="earlier-versions">Earlier versions</h2>
-<p>In earlier versions of JsonApiDotNetCore, you needed to create controllers that inherit from <code>JsonApiController&lt;TResource, TId&gt;</code>. For example:</p>
+<h2 id="explicit-controllers">Explicit controllers</h2>
+<p>To define your own controller class, inherit from <code>JsonApiController&lt;TResource, TId&gt;</code>. For example:</p>
 <pre><code class="lang-c#">public class ArticlesController : JsonApiController&lt;Article, Guid&gt;
 {
     public ArticlesController(IJsonApiOptions options, IResourceGraph resourceGraph,