refactor: 🔨 Update JsonApiOk function and docs to align with what it actually does

Author: erlendellefsen

CLAUDE.md

@@ -73,6 +73,12 @@ Documentation is built using DocFX and deployed to GitHub Pages. The documentati
    - Query parameters: `QueryParameters`, `FilterParameter`, `SortParameter`
    - Errors: `JsonApiError`, `JsonApiErrorResponse`
 
+5. **Attributes** (`Attributes/`)
+   - `AllowedIncludesAttribute`: Restricts which relationships can be included in responses
+   
+6. **Validation** (`Validation/`)
+   - `IncludePatternValidator`: Validates include patterns with wildcard support
+
 ### Key Patterns
 
 - **Convention-based mapping**: Properties are automatically mapped from C# PascalCase to JSON camelCase
@@ -82,6 +88,7 @@ Documentation is built using DocFX and deployed to GitHub Pages. The documentati
 - **Filter expressions**: Complex filtering with operators (eq, ne, gt, lt, contains, etc.), logical grouping, and enum support
 - **JSON column detection**: Collections and complex objects without ID properties are automatically mapped as JSON attributes instead of relationships (useful for EF Core owned entities stored as JSON columns)
 - **Pagination safety**: Invalid page numbers are automatically clamped to valid ranges (page 1 for negative/zero, last page for overflow)
+- **Include whitelisting**: Use `AllowedIncludesAttribute` on controller actions to restrict which relationships can be included, preventing unauthorized data exposure
 
 ### Service Registration
 
@@ -124,12 +131,14 @@ Tests are organized by component:
 
 1. **Query Operations**: Extend `FilterExpressionBuilder` and add corresponding operators to `FilterOperator` enum
 2. **New Controllers**: Inherit from `JsonApiController` and use provided helper methods
-3. **Entity Mapping**: Use `EntityMapper` for custom mapping rules and automatic detection of relationships vs attributes
+3. **Entity Mapping**: Use `EntityMapper` for automatic detection of relationships vs attributes based on ID properties
 4. **Testing**: Follow existing patterns with xUnit and Moq, test both success and error scenarios
 
 ### Common Patterns
 
-- Controllers should inherit from `JsonApiController` and use `JsonApiOkAsync(queryable, "resourceType")`
+- Controllers should inherit from `JsonApiController`
+- Use `JsonApiOkAsync(queryable, "resourceType")` for collections with full query processing
+- Use `JsonApiOk(entity, "resourceType")` for already-loaded entities or collections
 - Entity types should have an `Id` property (auto-detected by `EntityMapper.GetIdProperty()`)
 - Use `QueryParameters queryParams = GetJsonApiQueryParameters()` to access parsed query parameters
 - For manual mapping, use `JsonApiMapper.ToDocument()` or `ToCollectionDocument()`

JsonApiToolkit/Controllers/JsonApiController.cs

@@ -57,26 +57,22 @@ protected QueryParameters GetJsonApiQueryParameters()
     /// Creates a 200 OK response containing a single resource as a JSON:API document.
     /// </summary>
     /// <typeparam name="T">The entity type being returned</typeparam>
-    /// <param name="entity">The entity to serialize into the response</param>
+    /// <param name="entity">The already-loaded entity to serialize into the response</param>
     /// <param name="resourceType">The JSON:API resource type identifier (typically the entity name in camelCase)</param>
     /// <returns>An IActionResult with a properly formatted JSON:API document</returns>
     /// <remarks>
-    /// Automatically processes any "include" parameters from the request and adds the specified relationships
-    /// to the included section of the response.
+    /// Serializes the provided entity into JSON:API format. Any relationships that are already loaded
+    /// on the entity will be included in the response.
     /// </remarks>
     protected IActionResult JsonApiOk<T>(T entity, string resourceType)
         where T : class
     {
         string baseUrl = $"{Request.Scheme}://{Request.Host}{Request.Path}";
-        QueryParameters queryParams = GetJsonApiQueryParameters();
-        var mappedIncludes = EfIncludePathHelper.MapIncludePathsToClrProperties<T>(
-            queryParams.Include
-        );
         JsonApiDocument<ResourceObject> document = JsonApiMapper.ToDocument(
             entity,
             resourceType,
             baseUrl,
-            mappedIncludes
+            null // No include filtering - serialize all loaded relationships
         );
         return Ok(document);
     }
@@ -85,14 +81,13 @@ protected IActionResult JsonApiOk<T>(T entity, string resourceType)
     /// Creates a 200 OK response containing a collection of resources as a JSON:API document.
     /// </summary>
     /// <typeparam name="T">The entity type of the collection items</typeparam>
-    /// <param name="entities">The collection of entities to serialize into the response</param>
+    /// <param name="entities">The already-loaded collection of entities to serialize into the response</param>
     /// <param name="resourceType">The JSON:API resource type identifier (typically the entity name in camelCase)</param>
     /// <param name="paginationMeta">Optional pagination metadata to include in the response</param>
     /// <returns>An IActionResult with a properly formatted JSON:API collection document</returns>
     /// <remarks>
-    /// Automatically processes any "include" parameters from the request and adds the specified relationships
-    /// to the included section of the response. When pagination metadata is provided, adds pagination links
-    /// to the response.
+    /// Serializes the provided collection into JSON:API format. Any relationships that are already loaded
+    /// on the entities will be included in the response. When pagination metadata is provided, adds pagination links.
     /// </remarks>
     protected IActionResult JsonApiOk<T>(
         IEnumerable<T> entities,
@@ -102,16 +97,12 @@ protected IActionResult JsonApiOk<T>(
         where T : class
     {
         string baseUrl = GetFullRequestUrl();
-        QueryParameters queryParams = GetJsonApiQueryParameters();
-        var mappedIncludes = EfIncludePathHelper.MapIncludePathsToClrProperties<T>(
-            queryParams.Include
-        );
         JsonApiCollectionDocument<ResourceObject> document = JsonApiMapper.ToCollectionDocument(
             entities,
             resourceType,
             baseUrl,
             paginationMeta,
-            mappedIncludes
+            null // No include filtering - serialize all loaded relationships
         );
         return Ok(document);
     }
@@ -202,22 +193,19 @@ string resourceType
     /// <returns>An IActionResult with Status201Created and a properly formatted JSON:API document</returns>
     /// <remarks>
     /// Sets the Location header to the resource's URL and includes the resource in the response body.
-    /// Automatically processes any "include" parameters from the request to add related resources.
+    /// Serializes the provided entity into JSON:API format. Any relationships that are already loaded
+    /// on the entity will be included in the response.
     /// </remarks>
     protected IActionResult JsonApiCreated<T>(T entity, string resourceType, string id)
         where T : class
     {
         string baseUrl = $"{Request.Scheme}://{Request.Host}{Request.PathBase}{Request.Path}";
         string selfUrl = $"{baseUrl}/{id}";
-        QueryParameters queryParams = GetJsonApiQueryParameters();
-        var mappedIncludes = EfIncludePathHelper.MapIncludePathsToClrProperties<T>(
-            queryParams.Include
-        );
         JsonApiDocument<ResourceObject> document = JsonApiMapper.ToDocument(
             entity,
             resourceType,
             selfUrl,
-            mappedIncludes
+            null // No include filtering - serialize all loaded relationships
         );
         return Created(selfUrl, document);
     }

docs/docs/api-controller-examples.md

@@ -30,7 +30,7 @@ public class BooksController : JsonApiController
 [HttpGet]
 public async Task<IActionResult> GetBooks()
 {
-    IQueryable<Book> books = _context.Books;
+    IQueryable<Book> books = _context.Books.AsQueryable();
     return await JsonApiOkAsync(books, "book");
 }
 ```
@@ -124,11 +124,11 @@ public async Task<IActionResult> DeleteBook(int id)
 public async Task<IActionResult> SearchBooks()
 {
     // The filtering is handled automatically by JsonApiOkAsync
-    // But you can also apply custom logic before the standard processing
+    IQueryable<Book> books = _context.Books.AsQueryable();
 
-    var books = _context.Books
-        .Where(b => b.IsPublished); // Custom business logic
-        
+    // But you can also apply custom logic before the standard processing
+    books = books.Where(b => b.IsPublished); // Custom business logic
+
     return await JsonApiOkAsync(books, "book");
 }
 ```
@@ -243,7 +243,7 @@ public async Task<IActionResult> GetPublicOnly()
 ## Pro Tips
 
 1. **Always use exception types** instead of returning error ActionResults - the filter handles conversion automatically
-2. **Use JsonApiOkAsync for collections** - it provides full query parameter support
-3. **Use JsonApiOk for single resources** - simpler and faster for individual entities
+2. **Use JsonApiOkAsync for collections** when you want automatic query processing (filtering, sorting, pagination)
+3. **Use JsonApiOk for already-loaded data** when you've fetched and processed entities yourself
 4. **Use AllowedIncludes** - restrict relationship access for security and performance
 

docs/docs/getting-started.md

@@ -5,7 +5,7 @@ This guide walks you through installing and configuring JsonApiToolkit in your .
 ## Prerequisites
 
 - [.NET 9.0 SDK](https://dotnet.microsoft.com/download) or later.
-- An ASP.NET Core project (typically an API project).
+- An ASP.NET Core project.
 
 ## Installation