Add book and chapter titles to search API results

[rashadkhan359]

Purpose

Add the ability to include book and chapter titles in the /api/search endpoint results through an optional include parameter. This makes it easier for API consumers to show the full content hierarchy context for search results without additional API calls.

Closes

API Request #5140

Implementation

New Features

• Added optional include parameter to /api/search endpoint
• Supported include options:
  • titles - Includes book_title and chapter_title for applicable entities
  • tags - Include associated tags (existing functionality now controlled via include)

Multiple includes can be combined using comma separation.(if we want to extend on it.)

Changes

• Added new ApiEntityListFormatter::withRelatedTitles(), ApiEntityListFormatter::loadRelatedTitles() and SearchApiController::parseIncludes() method.
• Modified following existing methods:
  • SearchApiController::$rules
  • SearchApiController::all()
  • ApiEntityListFormatter::format()
• Added support for modular includes in search API controller
• Added comprehensive tests for new functionality

Technical Details

• Uses eager loading to prevent N+1 queries
• Might not maintain backward compatibility (specifically since tags were already included by default but now we need to pass it in include for it to be included. This behavior if problematic can be altered easily.)
• Follows existing BookStack API patterns
• Includes full test coverage

Testing

New test cases cover:

• Including/excluding titles
• Multiple include combinations
• Input validation
• Edge cases

All existing tests pass without modification.

Documentation

The API documentation has been edited as well to cater to the new changes.

Example Request

GET /api/search?query=example&include=titles,tags

Example Response

{
  "data": [
    {
      "id": 84,
      "book_id": 1,
      "slug": "a-chapter-for-cats",
      "name": "A chapter for cats",
      "created_at": "2021-11-14T15:57:35.000000Z",
      "updated_at": "2021-11-14T15:57:35.000000Z",
      "type": "chapter",
      "url": "https://example.com/books/my-book/chapter/a-chapter-for-cats",
      "book_title": "Cats",
      "preview_html": {
        "name": "A chapter for <strong>cats</strong>",
        "content": "...once a bunch of <strong>cats</strong> named tony...behaviour of <strong>cats</strong> is unsuitable"
      },
      "tags": []
    },
    {
      "name": "The hows and whys of cats",
      "id": 396,
      "slug": "the-hows-and-whys-of-cats",
      "book_id": 1,
      "chapter_id": 75,
      "draft": false,
      "template": false,
      "created_at": "2021-05-15T16:28:10.000000Z",
      "updated_at": "2021-11-14T15:56:49.000000Z",
      "type": "page",
      "url": "https://example.com/books/my-book/page/the-hows-and-whys-of-cats",
      "book_title": "Cats",
      "chapter_title": "A chapter for cats",
      "preview_html": {
        "name": "The hows and whys of <strong>cats</strong>",
        "content": "...people ask why <strong>cats</strong>? but there are...the reason that <strong>cats</strong> are fast are due to..."
      },
      "tags": [
        {
          "name": "Animal",
          "value": "Cat",
          "order": 0
        },
        {
          "name": "Category",
          "value": "Top Content",
          "order": 0
        }
      ]
    },
    {
      "name": "How advanced are cats?",
      "id": 362,
      "slug": "how-advanced-are-cats",
      "book_id": 13,
      "chapter_id": 73,
      "draft": false,
      "template": false,
      "created_at": "2020-11-29T21:55:07.000000Z",
      "updated_at": "2021-11-14T16:02:39.000000Z",
      "type": "page",
      "url": "https://example.com/books/my-book/page/how-advanced-are-cats",
      "book_title": "Cats",
      "chapter_title": "A chapter for cats",
      "preview_html": {
        "name": "How advanced are <strong>cats</strong>?",
        "content": "<strong>cats</strong> are some of the most advanced animals in the world."
      },
      "tags": []
    }
  ],
  "total": 3
}

PS

This is my first-ever contribution to open source projects. I kindly ask for a thorough review, and I'm eager to improve upon any mistakes I may have made.