No enum component $ref in query parameter object

[doei]

I may be doing something wrong here...

I have an enum defined liked this:

class TransportMode(models.TextChoices):
    FOOT = "FOOT"
    BIKE = "BIKE"

With a request/response serializer pair, like those

class AddressDistanceSerializer(serializers.Serializer):
    # ...
    transport_mode = serializers.ChoiceField(choices=TransportMode.choices)

class AddressDistanceResponseSerializer(serializers.Serializer):
    # ...
    transport_mode = serializers.ChoiceField(choices=TransportMode.choices)

The enum only gets a component when present in a response serializer, like this:

components:
  schemas:
    AddressDistanceResponse:
      type: object
      properties:
        distance:
          type:
          - number
          - 'null'
          format: double
        transportMode:
          $ref: '#/components/schemas/TransportModeEnum'
      required:
      - transportMode
    TransportModeEnum:
      enum:
      - FOOT
      - BIKE
      type: string

@extend_schema(
    request=AddressDistanceSerializer, # whether I set this or not doesn't seem to change anything
    parameters=[AddressDistanceSerializer], # this works but never picks up the component
    summary="Get address distance",
    responses={200: AddressDistanceResponseSerializer},
)

The best I can do is use the parameters kwarg of the extend_schema decorator, which yields the following:

  /retrieve_distance:
    get:
      operationId: retrieveDistance
      summary: Get address distance
      parameters:
      - in: query
        name: transportMode
        schema:
          enum:
          - FOOT
          - BIKE
          type: string
          minLength: 1
        description: |-
          * `FOOT` - Foot
          * `BIKE` - Bike

I would expect the query schema to be a $ref: '#/components/schemas/TransportModeEnum', just like for the response, but it doesn't seem to be the case.

Because of this discrepancy the client generator we're trying to use (https://github.com/astahmer/openapi-zod-client) , is not referencing the enum in the request params...

Is this normal behaviour ? As I understand it, $refs are allowed within parameters objects schemas (https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#parameter-object)...

[tfranzel]

I'm aware of this issue. We kind of missed the opportunity to add that by default because already to many people depended on the current solution and adding more choices may introduce additional warnings and potential collisions.

However, this should be opt-in, but I never got around doing it. Putting it on the backlog.

[theodor-franke]

Would love to see this feature implemented