Moody/doc display names (open5e#757)

* add display name field to documents for common names

* add display name to endpoint with fallback

* update tests with new field

Author: eepMoody

.cursor

@@ -0,0 +1,188 @@
+# Open5e API Project Documentation for AI Assistants
+
+## Project Overview
+This is the Open5e API - a Django REST API providing D&D 5th Edition game content data.
+- **Main API versions**: v1 (`api/`) and v2 (`api_v2/`)
+- **Primary focus**: v2 API is the current development target
+- **Database**: SQLite for development, supports PostgreSQL for production
+- **Framework**: Django REST Framework with custom serializers
+
+## Project Structure
+
+### Key Directories
+- `api/` - Legacy v1 API (mostly maintenance mode)
+- `api_v2/` - Current v2 API development
+  - `models/` - Database models
+  - `serializers/` - DRF serializers with inheritance patterns
+  - `views/` - API viewsets
+  - `tests/` - Approval tests (see Testing section)
+- `data/` - JSON fixture files for database seeding
+  - `v1/` - Legacy data
+  - `v2/` - Current data format
+- `server/` - Django settings and configuration
+
+### Important Files
+- `manage.py` - Standard Django management
+- `api/management/commands/quicksetup.py` - Database rebuild script
+- `Pipfile` - Python dependencies (using pipenv)
+
+## Database Setup & Management
+
+### Quick Setup (CRITICAL for development)
+```bash
+python manage.py quicksetup --clean --noindex
+```
+This command:
+- Cleans existing database/static files/search indexes
+- Runs migrations
+- Loads ALL fixture data from `data/v1/` and `data/v2/`
+- Collects static files
+- **Always run this after schema changes or when fixture data is updated**
+
+### Manual Steps
+```bash
+python manage.py makemigrations api_v2  # For model changes
+python manage.py migrate                # Apply migrations
+python manage.py collectstatic         # Static files
+```
+
+### Fixture Data Loading
+- Fixtures are automatically loaded by quicksetup
+- Data format: JSON files with Django fixture format
+- v2 fixtures in `data/v2/publisher/document/` structure
+
+## Testing System (APPROVAL TESTS)
+
+### How Approval Tests Work
+The project uses **approval testing** - tests compare actual API responses against pre-approved JSON files.
+
+#### Test Structure
+- Tests in: `api_v2/tests/test_objects.py`
+- Approved responses: `api_v2/tests/responses/*.approved.json`
+- Failed test responses: `api_v2/tests/responses/*.received.json`
+
+#### Running Tests
+```bash
+# Requires running server for integration tests
+python manage.py runserver 8000 &
+python -m pytest api_v2/tests/test_objects.py -v
+pkill -f "python manage.py runserver"  # Stop server
+```
+
+#### Updating Test Expectations (IMPORTANT PATTERN)
+When API responses change (like adding new fields):
+
+1. **Run tests** - they will fail and generate `.received.json` files
+2. **Review changes** in the `.received.json` files
+3. **Update all at once** (EFFICIENT METHOD):
+   ```bash
+   cd api_v2/tests/responses/
+   for file in *.received.json; do 
+     mv "$file" "${file%.received.json}.approved.json"
+   done
+   ```
+4. **Re-run tests** to verify they pass
+
+**DO NOT** manually edit `.approved.json` files - use the rename pattern above!
+
+## API v2 Serializer Patterns
+
+### Inheritance Hierarchy
+- `GameContentSerializer` - Base class for all game content
+- `DocumentSerializer` - Full document serialization
+- `DocumentSummarySerializer` - Lightweight document refs (for FKs)
+
+### Common Patterns
+
+#### Fallback Properties
+When adding optional display fields, use model properties with fallbacks:
+```python
+# In model
+@property
+def display_name_or_name(self):
+    if self.display_name and self.display_name.strip():
+        return self.display_name
+    return self.name
+
+# In serializer  
+display_name = serializers.SerializerMethodField()
+
+def get_display_name(self, obj):
+    return obj.display_name_or_name
+```
+
+#### Document Relationships
+- Full documents: Use `DocumentSerializer` 
+- FK references: Use `DocumentSummarySerializer`
+- Check serializer `fields = '__all__'` vs specific field lists
+
+## Development Workflow
+
+### Adding New Fields
+1. **Add field to model** in `api_v2/models/`
+2. **Create migration**: `python manage.py makemigrations api_v2 --name descriptive_name`
+3. **Update serializers** if needed
+4. **Run quicksetup** to rebuild DB with fixture data: `python manage.py quicksetup --clean --noindex`
+5. **Update tests** using the `.received.json` → `.approved.json` rename pattern
+6. **Test the API** with running server
+
+### API Testing
+```bash
+# Start server
+python manage.py runserver 8000 &
+
+# Test endpoints
+curl -s "http://localhost:8000/v2/documents/" | python -m json.tool
+
+# Stop server
+pkill -f "python manage.py runserver"
+```
+
+## Common Gotchas
+
+### Database State
+- **Always run quicksetup after model changes** - migrations alone don't reload fixture data
+- Fixture data may have different values than what's in migrations
+- Database relationships are complex - FK dependencies matter for loading order
+
+### Test Failures
+- Tests are integration tests requiring a running server
+- Connection refused errors = server not running
+- Approval mismatches = API response changed, update `.approved.json` files
+- Tests expect exact JSON matches including field order
+
+### Serializer Field Order
+- JSON field order matters for approval tests
+- SerializerMethodFields appear in declaration order
+- `fields = '__all__'` includes all model fields + method fields
+
+## Useful Commands
+
+```bash
+# Full development reset
+python manage.py quicksetup --clean --noindex
+
+# Run specific test
+python -m pytest api_v2/tests/test_objects.py::TestObjects::test_document_example -v
+
+# Find fixture files
+find data/v2/ -name "*.json" | grep -i document
+
+# Check API response
+curl -s "http://localhost:8000/v2/documents/srd-2024/" | python -m json.tool
+
+# Update all failing tests at once
+cd api_v2/tests/responses/ && for file in *.received.json; do mv "$file" "${file%.received.json}.approved.json"; done
+```
+
+## Project Conventions
+
+### Model Patterns
+- Inherit from `HasName`, `HasDescription` abstracts when appropriate
+- Use `key_field()` for primary keys (CharField, not AutoField)
+- Foreign keys typically reference document for data lineage
+
+### API Design
+- RESTful endpoints: `/v2/modelname/` and `/v2/modelname/key/`
+- Consistent field naming across models
+- Rich relationship serialization (nested objects, not just IDs)

api_v2/migrations/0049_add_document_display_name.py

@@ -0,0 +1,18 @@
+# Generated by Django 5.2.1 on 2025-06-07 15:31
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('api_v2', '0048_service_name'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='document',
+            name='display_name',
+            field=models.CharField(blank=True, help_text='Display name for the document, used for presentation purposes.', max_length=255, null=True),
+        ),
+    ]

api_v2/models/document.py

@@ -30,6 +30,12 @@ class Document(HasName, HasDescription):
     author = models.TextField(
         help_text='Author or authors.')
 
+    display_name = models.CharField(
+        max_length=255,
+        blank=True,
+        null=True,
+        help_text="Display name for the document, used for presentation purposes.")
+
     publication_date = models.DateTimeField(
         help_text="Date of publication, or null if unknown."
     )
@@ -41,6 +47,13 @@ class Document(HasName, HasDescription):
     distance_unit = distance_unit_field()
     weight_unit = distance_unit_field()
 
+    @property
+    def display_name_or_name(self):
+        """Returns display_name if it exists and is not blank, otherwise returns name."""
+        if self.display_name and self.display_name.strip():
+            return self.display_name
+        return self.name
+
     @property
     def stats(self):
         stats = []

api_v2/serializers/document.py

@@ -58,6 +58,10 @@ class DocumentSerializer(GameContentSerializer):
     licenses = LicenseSummarySerializer(read_only=True, many=True)
     publisher = PublisherSummarySerializer(read_only=True)
     gamesystem = GameSystemSummarySerializer(read_only=True)
+    display_name = serializers.SerializerMethodField()
+
+    def get_display_name(self, obj):
+        return obj.display_name_or_name
 
     class Meta:
         model = models.Document
@@ -70,7 +74,11 @@ class DocumentSummarySerializer(GameContentSerializer):
     '''
     publisher = PublisherSummarySerializer()
     gamesystem = GameSystemSummarySerializer()
+    display_name = serializers.SerializerMethodField()
+
+    def get_display_name(self, obj):
+        return obj.display_name_or_name
 
     class Meta:
         model = models.Document
-        fields = ['name', 'key', 'publisher', 'gamesystem', 'permalink']
+        fields = ['name', 'key', 'display_name', 'publisher', 'gamesystem', 'permalink']

api_v2/tests/responses/TestObjects.test_alignment_example.approved.json

@@ -3,6 +3,7 @@
     "document": {
         "author": "Mike Mearls, Jeremy Crawford, Chris Perkins, Rodney Thompson, Peter Lee, James Wyatt, Robert J. Schwalb, Bruce R. Cordell, Chris Sims, and Steve Townshend, based on original material by E. Gary Gygax and Dave Arneson.",
         "desc": "The System Reference Document (SRD) contains guidelines for publishing content under the Open-Gaming License (OGL) or Creative Commons. The Dungeon Masters Guild also provides self-publishing opportunities for individuals and groups.",
+        "display_name": "5e 2014 Rules",
         "distance_unit": "feet",
         "gamesystem": {
             "key": "o5e",

api_v2/tests/responses/TestObjects.test_armor_example.approved.json

@@ -5,6 +5,7 @@
     "ac_display": "17",
     "category": "heavy",
     "document": {
+        "display_name": "5e 2014 Rules",
         "gamesystem": {
             "key": "o5e",
             "name": "5th Edition",

api_v2/tests/responses/TestObjects.test_background_example.approved.json

@@ -28,6 +28,7 @@
     ],
     "desc": "You have spent your life in the service of a temple to a specific god or pantheon of gods. You act as an intermediary between the realm of the holy and the mortal world, performing sacred rites and offering sacrifices in order to conduct worshipers into the presence of the divine. You are not necessarily a cleric performing sacred rites is not the same thing as channeling divine power.\r\n\r\nChoose a god, a pantheon of gods, or some other quasi-divine being from among those listed in \"Fantasy-Historical Pantheons\" or those specified by your GM, and work with your GM to detail the nature of your religious service. Were you a lesser functionary in a temple, raised from childhood to assist the priests in the sacred rites? Or were you a high priest who suddenly experienced a call to serve your god in a different way? Perhaps you were the leader of a small cult outside of any established temple structure, or even an occult group that served a fiendish master that you now deny.",
     "document": {
+        "display_name": "5e 2014 Rules",
         "gamesystem": {
             "key": "o5e",
             "name": "5th Edition",

api_v2/tests/responses/TestObjects.test_class_example.approved.json

@@ -1,6 +1,7 @@
 {
     "caster_type": "NONE",
     "document": {
+        "display_name": "5e 2014 Rules",
         "gamesystem": {
             "key": "o5e",
             "name": "5th Edition",

api_v2/tests/responses/TestObjects.test_condition_example.approved.json

@@ -1,6 +1,7 @@
 {
     "desc": "* A stunned creature is incapacitated (see the condition), can\u2019t move, and can speak only falteringly.\r\n* The creature automatically fails Strength and Dexterity saving throws.\r\n* Attack rolls against the creature have advantage.",
     "document": {
+        "display_name": "5e 2014 Rules",
         "gamesystem": {
             "key": "o5e",
             "name": "5th Edition",

api_v2/tests/responses/TestObjects.test_creature_ancient_example.approved.json

@@ -182,6 +182,7 @@
     "creaturesets": [],
     "darkvision_range": 120.0,
     "document": {
+        "display_name": "5e 2014 Rules",
         "gamesystem": {
             "key": "o5e",
             "name": "5th Edition",