Fix nullable metadata loss for OpenAPI 3.1 choice fields with ENUM_ADD_EXPLICIT_BLANK_NULL_CHOICE=False

[mwhansen]

Description

Fixes nullable metadata loss for OpenAPI 3.1 choice fields when using ENUM_ADD_EXPLICIT_BLANK_NULL_CHOICE=False.

Problem

When using OAS_VERSION="3.1.0" with ENUM_ADD_EXPLICIT_BLANK_NULL_CHOICE=False, nullable choice fields were losing their nullable: true metadata during enum postprocessing, causing client generation issues.

Affected Configuration

SPECTACULAR_SETTINGS = {
    "OAS_VERSION": "3.1.0",
    "ENUM_ADD_EXPLICIT_BLANK_NULL_CHOICE": False,
}

Symptoms

Nullable choice fields defined like:

pet_type = serializers.ChoiceField(allow_null=True, choices=PET_TYPE_CHOICES)

Were generating schemas without nullable information:

# Before (Broken)
petType:
  $ref: '#/components/schemas/PetTypeEnum'  # Missing nullable!

# After (Fixed)  
petType:
  allOf:
    - $ref: '#/components/schemas/PetTypeEnum'
  nullable: true

Root Cause

1. OpenAPI 3.1 converts nullable enums to type=['string', 'null']
2. Enum postprocessing removes 'null' from type array (line 160 in hooks.py)
3. When ENUM_ADD_EXPLICIT_BLANK_NULL_CHOICE=False, no separate NullEnum component is created
4. Result: nullable information lost entirely

Files Changed

• drf_spectacular/hooks.py: Core fix for nullable preservation
• tests/test_regressions.py: Regression test to prevent future issues

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.50%. Comparing base (39cb3d5) to head (f428d95).

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1454   +/-   ##
=======================================
  Coverage   98.49%   98.50%           
=======================================
  Files          76       76           
  Lines        9266     9286   +20     
=======================================
+ Hits         9127     9147   +20     
  Misses        139      139           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[tfranzel]

Hey @mwhansen,

Thanks for the PR. I finally had some time to review this. Unfortunately, I think we cannot do this.

nullable: true is not a thing anymore in OAS >= 3.1. Even if the schema validation itself does not fail, that statement is basically inert and is not supposed to have any effect anymore. So we kind of lost the ability to specify the null outside $ref with that change.

Furthermore, turning off ENUM_ADD_EXPLICIT_BLANK_NULL_CHOICE while having components (i.e. using the enum postproc hook) is a tradeoff. You will loose the null information for a simpler schema construction. There simply no sane way to reuse the same enum component in different serializers with different parametrisations (blank=True/False, null=True/False).

The only way to resolve this (without Null/BlankEnum) would be creating multiple versions of the same enum component with and without the blank/null, but that is even less desirable imho.