docs: document tags filter API and usage

- Add comprehensive API documentation for tags_filter parameter
- Document fuzzy matching behavior with examples
- Add user guide for tag-based filtering
- Document backward compatibility with genre_filter
- Include examples of fuzzy matching ("Sci Fi" → "Science Fiction")

Provides complete documentation for the new tags filter feature,
including API reference and user-facing documentation.

Relates to IMPLEMENTATION_TAGS_FILTER.md Phase 7
This commit is contained in:
2026-03-25 20:38:33 -04:00
parent dc0d037e06
commit ab86eec32f
2 changed files with 47 additions and 6 deletions
@@ -24,7 +24,7 @@ Search and filter media items with fuzzy matching support.
| -------------- | ------- | --------------------------------------------------- |
| author_filter | string | Fuzzy match author field |
| series_filter | string | Fuzzy match series field |
| genre_filter | string | Fuzzy match genre field |
| tags_filter | string | **Fuzzy match tags array** |
| language_filter| string | Fuzzy match language field |
| year_min | integer | Minimum copyright year (exact range) |
| year_max | integer | Maximum copyright year (exact range) |
@@ -35,7 +35,7 @@ Search and filter media items with fuzzy matching support.
| Parameter | Type | Description |
| ---------- | ------ | ---------------------------------------------- |
| authors | string | Search author values for autocomplete dropdown |
| genres | string | Search genre values for autocomplete dropdown |
| tagss | string | Search tags values for autocomplete dropdown |
| series | string | Search series values for autocomplete dropdown |
| languages | string | Search language values for autocomplete |
@@ -66,7 +66,7 @@ Use double quotes for exact phrase matching:
**Text filters (fuzzy):**
- `author_filter=asimov` → fuzzy matches author field
- `genre_filter=scifi` → fuzzy matches genre field
- `tags_filter=scifi` → fuzzy matches tags field
**Exact filters:**
- `year_min=2000&year_max=2010` → exact year range
@@ -115,7 +115,7 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Fiction books from 2000-2010:
```http
GET /api/media-items/search?library_id=123e4567-e89b-12d3-a456-426614174000&genre_filter=fiction&year_min=2000&year_max=2010
GET /api/media-items/search?library_id=123e4567-e89b-12d3-a456-426614174000&tags_filter=fiction&year_min=2000&year_max=2010
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```
@@ -147,8 +147,9 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
{
"id": "uuid",
"title": "Foundation",
"author": "Asimov, Isaac",
"library_id": "...",
"author": "Isaac Asimov",
"tags": ["Science Fiction", "Adventure"],
"library_id": "uuid",
"library_name": "E-Books"
}
]
@@ -172,3 +173,7 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
| 400 | Missing library_id |
| 401 | Invalid or expired token |
| 404 | No results found |
### Backward Compatibility
The `genre_filter` parameter is **deprecated but still supported** for backward compatibility. It will return 0 results for books imported from Calibre (genre field is NULL).