hungryroot/jira/be_6934_fix_serializer_name_collisions_in_public_swagger_causing_v3_apis_to_reference_v2_serializers.org

BE-6934 Fix serializer name collisions in public Swagger causing V3 APIs to reference V2 serializers

Tasks

workhungryrootbe6934ep411docsspikesprint103

Wed Feb 11, 2026

workhungryrootbe6934ep411pullrequestsprint103

workhungryrootbe6934ep411pullrequestsprint103ciapiproject

Let’s do a mini spike and see what is needed for this since there are many APIs

we can cut tickets as needed for the individual endpoints.

The newly added Public schema in Swagger is causing serializer name collisions

that result in the v3 Discovery Home API being documented with v2 serializers.

This creates incorrect schema output in Swagger and is likely to cause client

confusion, especially during migration from v2 to v3.

Root cause appears to be overlapping serializer class names across v2 and v3

that are not being properly disambiguated in the Public Swagger schema. Because

of this, Spectacular is resolving the wrong serializer when generating the

OpenAPI spec.

+ v3 Discovery Home API is incorrectly documented using v2 serializers

+ This issue can affect any v3 serializer with a name collision

+ Clients relying on Swagger for schema validation or migration guidance may be misled

1. Investigate how the Public Swagger schema is generated

2. Update SPECTACULAR_SETTINGS to avoid serializer name collisions, for example by:

3. Enabling or adjusting serializer component name overrides

4. Adding explicit component name prefixes/suffixes for v2 vs v3 serializers

5. Using Spectacular settings or hooks to ensure v3 serializers are uniquely named

6. Validate that the v3 Discovery Home API and other v3 endpoints now reference the correct serializers in Swagger

Ensure Swagger accurately reflects v3 serializers for v3 APIs, preventing client

confusion and enabling a clean migration path from v2 to v3 Discovery Home.