feat: Add parameter description to properties

Author: alexifm

openapi_python_client/parser/openapi.py

@@ -220,6 +220,7 @@ def _add_parameters(
                 data=param.param_schema,
                 schemas=schemas,
                 parent_name=endpoint.name,
+                description=param.description,
             )
             if isinstance(prop, ParseError):
                 return ParseError(detail=f"cannot parse parameter of endpoint {endpoint.name}", data=prop.data), schemas

openapi_python_client/parser/properties/__init__.py

@@ -199,7 +199,7 @@ def inner_properties_with_template(self) -> Iterator[Property]:
 
 
 def _string_based_property(
-    name: str, required: bool, data: oai.Schema
+    name: str, required: bool, data: oai.Schema, description: Optional[str]
 ) -> Union[StringProperty, DateProperty, DateTimeProperty, FileProperty]:
     """ Construct a Property from the type "string" """
     string_format = data.schema_format
@@ -209,20 +209,23 @@ def _string_based_property(
             required=required,
             default=convert("datetime.datetime", data.default),
             nullable=data.nullable,
+            description=description,
         )
     elif string_format == "date":
         return DateProperty(
             name=name,
             required=required,
             default=convert("datetime.date", data.default),
             nullable=data.nullable,
+            description=description,
         )
     elif string_format == "binary":
         return FileProperty(
             name=name,
             required=required,
             default=None,
             nullable=data.nullable,
+            description=description,
         )
     else:
         return StringProperty(
@@ -231,6 +234,7 @@ def _string_based_property(
             required=required,
             pattern=data.pattern,
             nullable=data.nullable,
+            description=description,
         )
 
 
@@ -259,7 +263,12 @@ def build_model_property(
     for key, value in (data.properties or {}).items():
         prop_required = key in required_set
         prop, schemas = property_from_data(
-            name=key, required=prop_required, data=value, schemas=schemas, parent_name=class_name
+            name=key,
+            required=prop_required,
+            data=value,
+            schemas=schemas,
+            parent_name=class_name,
+            description=value.description,
         )
         if isinstance(prop, PropertyError):
             return prop, schemas
@@ -320,6 +329,7 @@ def build_enum_property(
     schemas: Schemas,
     enum: List[Union[str, int]],
     parent_name: Optional[str],
+    description: Optional[str],
 ) -> Tuple[Union[EnumProperty, PropertyError], Schemas]:
     """
     Create an EnumProperty from schema data.
@@ -379,13 +389,20 @@ def build_enum_property(
         reference=reference,
         values=values,
         value_type=value_type,
+        description=description,
     )
     schemas = attr.evolve(schemas, enums={**schemas.enums, prop.reference.class_name: prop})
     return prop, schemas
 
 
 def build_union_property(
-    *, data: oai.Schema, name: str, required: bool, schemas: Schemas, parent_name: str
+    *,
+    data: oai.Schema,
+    name: str,
+    required: bool,
+    schemas: Schemas,
+    parent_name: str,
+    description: Optional[str],
 ) -> Tuple[Union[UnionProperty, PropertyError], Schemas]:
     sub_properties: List[Property] = []
     for sub_prop_data in chain(data.anyOf, data.oneOf):
@@ -404,28 +421,35 @@ def build_union_property(
             default=default,
             inner_properties=sub_properties,
             nullable=data.nullable,
+            description=description,
         ),
         schemas,
     )
 
 
 def build_list_property(
-    *, data: oai.Schema, name: str, required: bool, schemas: Schemas, parent_name: str
+    *,
+    data: oai.Schema,
+    name: str,
+    required: bool,
+    schemas: Schemas,
+    parent_name: str,
+    description: Optional[str],
 ) -> Tuple[Union[ListProperty[Any], PropertyError], Schemas]:
     if data.items is None:
         return PropertyError(data=data, detail="type array must have items defined"), schemas
     inner_prop, schemas = property_from_data(
         name=f"{name}_item", required=True, data=data.items, schemas=schemas, parent_name=parent_name
     )
     if isinstance(inner_prop, PropertyError):
-        return PropertyError(data=inner_prop.data, detail=f"invalid data in items of array {name}"), schemas
     return (
         ListProperty(
             name=name,
             required=required,
             default=None,
             inner_property=inner_prop,
             nullable=data.nullable,
+            description=description,
         ),
         schemas,
     )
@@ -437,6 +461,7 @@ def _property_from_data(
     data: Union[oai.Reference, oai.Schema],
     schemas: Schemas,
     parent_name: str,
+    description: Optional[str],
 ) -> Tuple[Union[Property, PropertyError], Schemas]:
     """ Generate a Property from the OpenAPI dictionary representation of it """
     name = utils.remove_string_escapes(name)
@@ -451,22 +476,41 @@ def _property_from_data(
         return PropertyError(data=data, detail="Could not find reference in parsed models or enums"), schemas
     if data.enum:
         return build_enum_property(
-            data=data, name=name, required=required, schemas=schemas, enum=data.enum, parent_name=parent_name
+            data=data,
+            name=name,
+            required=required,
+            schemas=schemas,
+            enum=data.enum,
+            parent_name=parent_name,
+            description=description,
         )
     if data.anyOf or data.oneOf:
-        return build_union_property(data=data, name=name, required=required, schemas=schemas, parent_name=parent_name)
+        return build_union_property(
+            data=data,
+            name=name,
+            required=required,
+            schemas=schemas,
+            parent_name=parent_name,
+            description=description,
+        )
     if not data.type:
         return NoneProperty(name=name, required=required, nullable=False, default=None), schemas
 
     if data.type == "string":
-        return _string_based_property(name=name, required=required, data=data), schemas
+        return (
+            _string_based_property(
+                name=name, required=required, data=data, description=description
+            ),
+            schemas,
+        )
     elif data.type == "number":
         return (
             FloatProperty(
                 name=name,
                 default=convert("float", data.default),
                 required=required,
                 nullable=data.nullable,
+                description=description,
             ),
             schemas,
         )
@@ -477,6 +521,7 @@ def _property_from_data(
                 default=convert("int", data.default),
                 required=required,
                 nullable=data.nullable,
+                description=description,
             ),
             schemas,
         )
@@ -487,11 +532,19 @@ def _property_from_data(
                 required=required,
                 default=convert("bool", data.default),
                 nullable=data.nullable,
+                description=description,
             ),
             schemas,
         )
     elif data.type == "array":
-        return build_list_property(data=data, name=name, required=required, schemas=schemas, parent_name=parent_name)
+        return build_list_property(
+            data=data,
+            name=name,
+            required=required,
+            schemas=schemas,
+            parent_name=parent_name,
+            description=description,
+        )
     elif data.type == "object":
         return build_model_property(data=data, name=name, schemas=schemas, required=required, parent_name=parent_name)
     return PropertyError(data=data, detail=f"unknown type {data.type}"), schemas
@@ -504,9 +557,17 @@ def property_from_data(
     data: Union[oai.Reference, oai.Schema],
     schemas: Schemas,
     parent_name: str,
+    description: Optional[str] = None,
 ) -> Tuple[Union[Property, PropertyError], Schemas]:
     try:
-        return _property_from_data(name=name, required=required, data=data, schemas=schemas, parent_name=parent_name)
+        return _property_from_data(
+            name=name,
+            required=required,
+            data=data,
+            schemas=schemas,
+            parent_name=parent_name,
+            description=description,
+        )
     except ValidationError:
         return PropertyError(detail="Failed to validate default value", data=data), schemas
 

openapi_python_client/parser/properties/property.py

@@ -25,6 +25,7 @@ class Property:
     nullable: bool
     _type_string: ClassVar[str] = ""
     default: Optional[str] = attr.ib()
+    description: Optional[str]
     python_name: str = attr.ib(init=False)
 
     template: ClassVar[Optional[str]] = None