[http-client-python] Refine api_version argument doc

.chronus/changes/python-refine-api-version-doc-2026-4-15.md

@@ -0,0 +1,7 @@
+---
+changeKind: fix
+packages:
+  - "@typespec/http-client-python"
+---
+
+Refine `api_version` argument doc to show `None` as default value and include note about operation's default API version being used when not set

packages/http-client-python/generator/pygen/codegen/models/parameter.py

@@ -108,25 +108,24 @@ def description(self) -> str:
         type_description = self.type.description(is_operation_file=True)
         if type_description:
             base_description = add_to_description(base_description, type_description)
-        if self.optional and isinstance(self.type, ConstantType):
-            if self.is_api_version:
-                base_description = add_to_description(
-                    base_description,
-                    f"Known values are {self.get_declaration()}.",
-                )
-            else:
-                base_description = add_to_description(
-                    base_description,
-                    f"Known values are {self.get_declaration()} and None.",
-                )
+        if (self.optional or self.is_api_version) and isinstance(self.type, ConstantType):
+            base_description = add_to_description(
+                base_description,
+                f"Known values are {self.get_declaration()} and None.",
+            )
         if not (self.optional or self.client_default_value):
             base_description = add_to_description(base_description, "Required.")
-        if self.client_default_value is not None:
+        if self.is_api_version:
+            base_description = add_to_description(
+                base_description,
+                "Default value is None. If not set, the operation's default API version will be used.",
+            )
+        elif self.client_default_value is not None:
             base_description = add_to_description(
                 base_description,
                 f"Default value is {self.client_default_value_declaration}.",
             )
-        if self.optional and self.client_default_value is None:
+        elif self.optional:
             base_description = add_to_description(
                 base_description,
                 f"Default value is {self.client_default_value_declaration}.",