Org Web Adapter

Editing hungryroot/jira/be_6934_fix_serializer_name_collisions_in_public_swagger_causing_v3_apis_to_reference_v2_serializers.org

:PROPERTIES:
:ID:       fb758251-2997-44e5-acc7-bf9ff20cea4f
:END:
#+title: BE-6934 Fix serializer name collisions in public Swagger causing V3 APIs to reference V2 serializers

- source :: https://hungryroot.atlassian.net/browse/BE-6934
- tags ::   [[id:3a477c02-e26d-40f7-a719-0aa1cd169dd8][Hungryroot API Project]] 
- epic ::   [[id:86327fb4-0f66-4bc6-9068-c414cea77042][EP-411 Eng Parking Lot]]
- sprint :: [[id:c82bb209-ab05-47b1-8f5d-3eebfb7a808a][HR BE Sprint 103]]  [[id:30370b03-0b10-4105-87da-641cdda1bcb7][HR BE Sprint 104]]
- status :: [[id:87ee4162-0c60-41e4-8863-89e3ca8bf2f5][Status - Code Review]]

* Tasks
** DONE Make a list of the APIs that need updated Swagger docs to avoid collisions :work:hungryroot:be6934:ep411:docs:spike:sprint103:
:PROPERTIES:
:ID:       f17badb2-ab18-0504-c7a9-037c11a13749
:END:
<2026-02-11 Wed>

** DONE Open a PR with the overall serializer collision solution :work:hungryroot:be6934:ep411:pullrequest:sprint103:
:PROPERTIES:
:ID:       9faf952e-9a3d-0d26-67ca-03f430517eee
:END:
** DONE Fix issues from CI and PR reviews :work:hungryroot:be6934:ep411:pullrequest:sprint103:ci:api:project:
:PROPERTIES:
:ID:       976e77ab-1f57-db48-5151-7586f74b620b
:END:
* Description
https://hungryroot.slack.com/archives/C04GSJHFSTS/p1767710699937329

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.

** Impact

+ 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

** Proposed Approach

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

** Goal

Ensure Swagger accurately reflects v3 serializers for v3 APIs, preventing client
confusion and enabling a clean migration path from v2 to v3 Discovery Home.