Improved API documentation regarding empty fields

spoolman/api/v1/filament.py

@@ -119,19 +119,15 @@ async def find(
         alias="vendor_name",
         default=None,
         title="Vendor Name",
-        description=(
+        description="See vendor.name.",
-            "Partial case-insensitive search term for the filament vendor name. "
-            "Separate multiple terms with a comma."
-        ),
         deprecated=True,
     ),
     vendor_id_old: Optional[str] = Query(
         alias="vendor_id",
         default=None,
         title="Vendor ID",
-        description="Match an exact vendor ID. Separate multiple IDs with a comma.",
+        description="See vendor.id.",
         deprecated=True,
-        examples=["1", "1,2"],
     ),
     vendor_name: Optional[str] = Query(
         alias="vendor.name",
@@ -139,26 +135,33 @@ async def find(
         title="Vendor Name",
         description=(
             "Partial case-insensitive search term for the filament vendor name. "
-            "Separate multiple terms with a comma."
+            "Separate multiple terms with a comma. Specify an empty string to match filaments with no vendor name."
         ),
     ),
     vendor_id: Optional[str] = Query(
         alias="vendor.id",
         default=None,
         title="Vendor ID",
-        description="Match an exact vendor ID. Separate multiple IDs with a comma.",
+        description=(
+            "Match an exact vendor ID. Separate multiple IDs with a comma. "
+            "Specify -1 to match filaments with no vendor."
+        ),
         examples=["1", "1,2"],
     ),
     name: Optional[str] = Query(
         default=None,
         title="Filament Name",
-        description="Partial case-insensitive search term for the filament name. Separate multiple terms with a comma.",
+        description=(
+            "Partial case-insensitive search term for the filament name. Separate multiple terms with a comma. "
+            "Specify an empty string to match filaments with no name."
+        ),
     ),
     material: Optional[str] = Query(
         default=None,
         title="Filament Material",
         description=(
-            "Partial case-insensitive search term for the filament material. Separate multiple terms with a comma."
+            "Partial case-insensitive search term for the filament material. Separate multiple terms with a comma. "
+            "Specify an empty string to match filaments with no material."
         ),
     ),
     article_number: Optional[str] = Query(
@@ -166,7 +169,8 @@ async def find(
         title="Filament Article Number",
         description=(
             "Partial case-insensitive search term for the filament article number. "
-            "Separate multiple terms with a comma."
+            "Separate multiple terms with a comma. "
+            "Specify an empty string to match filaments with no article number."
         ),
     ),
     sort: Optional[str] = Query(

spoolman/api/v1/spool.py

@@ -79,48 +79,45 @@ async def find(
         alias="filament_name",
         default=None,
         title="Filament Name",
-        description="Partial case-insensitive search term for the filament name. Separate multiple terms with a comma.",
+        description="See filament.name.",
         deprecated=True,
     ),
     filament_id_old: Optional[str] = Query(
         alias="filament_id",
         default=None,
         title="Filament ID",
-        description="Match an exact filament ID. Separate multiple IDs with a comma.",
+        description="See filament.id.",
         deprecated=True,
-        examples=["1", "1,2"],
     ),
     filament_material_old: Optional[str] = Query(
         alias="filament_material",
         default=None,
         title="Filament Material",
-        description=(
+        description="See filament.material.",
-            "Partial case-insensitive search term for the filament material. Separate multiple terms with a comma."
-        ),
         deprecated=True,
     ),
     vendor_name_old: Optional[str] = Query(
         alias="vendor_name",
         default=None,
         title="Vendor Name",
-        description=(
+        description="See filament.vendor.name.",
-            "Partial case-insensitive search term for the filament vendor name. Separate multiple terms with a comma."
-        ),
         deprecated=True,
     ),
     vendor_id_old: Optional[str] = Query(
         alias="vendor_id",
         default=None,
         title="Vendor ID",
-        description="Match an exact vendor ID. Separate multiple IDs with a comma.",
+        description="See filament.vendor.id.",
         deprecated=True,
-        examples=["1", "1,2"],
     ),
     filament_name: Optional[str] = Query(
         alias="filament.name",
         default=None,
         title="Filament Name",
-        description="Partial case-insensitive search term for the filament name. Separate multiple terms with a comma.",
+        description=(
+            "Partial case-insensitive search term for the filament name. Separate multiple terms with a comma."
+            " Specify an empty string to match spools with no filament name."
+        ),
     ),
     filament_id: Optional[str] = Query(
         alias="filament.id",
@@ -134,7 +131,8 @@ async def find(
         default=None,
         title="Filament Material",
         description=(
-            "Partial case-insensitive search term for the filament material. Separate multiple terms with a comma."
+            "Partial case-insensitive search term for the filament material. Separate multiple terms with a comma. "
+            "Specify an empty string to match spools with no filament material."
         ),
     ),
     filament_vendor_name: Optional[str] = Query(
@@ -142,28 +140,34 @@ async def find(
         default=None,
         title="Vendor Name",
         description=(
-            "Partial case-insensitive search term for the filament vendor name. Separate multiple terms with a comma."
+            "Partial case-insensitive search term for the filament vendor name. Separate multiple terms with a comma. "
+            "Specify an empty string to match spools with no vendor name."
         ),
     ),
     filament_vendor_id: Optional[str] = Query(
         alias="filament.vendor.id",
         default=None,
         title="Vendor ID",
-        description="Match an exact vendor ID. Separate multiple IDs with a comma.",
+        description=(
+            "Match an exact vendor ID. Separate multiple IDs with a comma. "
+            "Set it to -1 to match spools with filaments with no vendor."
+        ),
         examples=["1", "1,2"],
     ),
     location: Optional[str] = Query(
         default=None,
         title="Location",
         description=(
-            "Partial case-insensitive search term for the spool location. Separate multiple terms with a comma."
+            "Partial case-insensitive search term for the spool location. Separate multiple terms with a comma. "
+            "Specify an empty string to match spools with no location."
         ),
     ),
     lot_nr: Optional[str] = Query(
         default=None,
         title="Lot/Batch Number",
         description=(
-            "Partial case-insensitive search term for the spool lot number. Separate multiple terms with a comma."
+            "Partial case-insensitive search term for the spool lot number. Separate multiple terms with a comma. "
+            "Specify an empty string to match spools with no lot nr."
         ),
     ),
     allow_archived: bool = Query(