chore: improve typing and annotations on BuildRequest

Add full annotations to all BuildRequest members, including the
verbose descriptions from the pre-pydantic API.  This produces much
better documentation in the redoc and api docs.  Also did a little
semantic reordering, so the flow of the docs is a bit better.

Signed-off-by: Eric Fahlgren <[email protected]>

asu/build_request.py

@@ -1,53 +1,148 @@
-from typing import Annotated, Optional
-
+from typing import Annotated
 from pydantic import BaseModel, Field
 
 from asu.config import settings
 
 
 class BuildRequest(BaseModel):
-    distro: str = "openwrt"
-    version: str
+    distro: Annotated[
+        str,
+        Field(
+            description="""
+                This parameter is currently optional since no other
+                distributions are supported.
+            """.strip(),
+        ),
+    ] = "openwrt"
+    version: Annotated[
+        str,
+        Field(
+            examples=["23.05.2"],
+            description="""
+                It is recommended to always upgrade to the latest version,
+                however it is possible to request older images for testing.
+            """.strip(),
+        ),
+    ]
     version_code: Annotated[
         str,
         Field(
-            default="",
-            description="It is possible to send the expected revision. "
-            "This allows to show the revision within clients before the "
-            "request. If the resulting firmware is a different revision, "
-            "the build results in an error.",
+            examples=["r26741-dcc4307205"],
+            description="""
+                It is possible to send the expected revision.  This allows to
+                show the revision within clients before the request. If the
+                resulting firmware is a different revision, the build results
+                in an error.
+            """.strip(),
         ),
     ] = ""
-    target: str
-    packages: Optional[list[str]] = []
-    profile: str
-    packages_versions: Optional[dict] = {}
-    defaults: Optional[
-        Annotated[
-            str,
-            Field(
-                default=None,
-                max_length=settings.max_defaults_length,
-                description="Custom shell script embedded in firmware image to be run on first\n"
-                "boot. This feature might be dropped in the future. Input file size\n"
-                f"is limited to {settings.max_defaults_length} bytes and cannot be exceeded.",
-            ),
-        ]
+    target: Annotated[
+        str,
+        Field(
+            examples=["ath79/generic"],
+            description="""
+            It is recommended to always upgrade to the latest version, however
+            it is possible to request older images for testing.
+            """.strip(),
+        ),
+    ]
+    profile: Annotated[
+        str,
+        Field(
+            examples=["8dev_carambola2"],
+            description="""
+                The ImageBuilder `PROFILE`.  Can be found with `ubus call
+                system board` as the `board_name` value.
+                """.strip(),
+        ),
+    ]
+    packages: Annotated[
+        list[str],
+        Field(
+            examples=[["vim", "tmux"]],
+            description="""
+                List of packages, either *additional* or *absolute* depending
+                of the `diff_packages` parameter.  This is augmented by the
+                `packages_versions` field, which allow you to additionally
+                specify the versions of the packages to be installed.
+            """.strip(),
+        ),
+    ] = []
+    packages_versions: Annotated[
+        dict,
+        Field(
+            examples=[{"vim": "1.2.3", "tmux": "2.3.4"}],
+            description="""
+                A dictionary of package names and versions.  This is an
+                alternate form of `packages`, in which the expected package
+                versions are specified for verification after the build has
+                completed.
+            """.strip(),
+        ),
+    ] = {}
+    diff_packages: Annotated[
+        bool,
+        Field(
+            description="""
+                This parameter determines if requested packages are seen as
+                *additional* or *absolute*. If set to `true` the packages are
+                seen as *absolute* and all default packages outside the
+                requested packages are removed. \n\n It is possible to brick
+                devices when requesting an incomplete list with this parameter
+                enabled since it may remove WiFi drivers or other essential
+                packages.
+            """.strip(),
+        ),
+    ] = False
+    defaults: Annotated[
+        str | None,
+        Field(
+            max_length=settings.max_defaults_length,
+            examples=['echo "Hello world"\nwifi restart\n'],
+            description=f"""
+                Custom shell script embedded in firmware image to be run
+                on first boot. This feature might be dropped in the future.
+                Input file size is limited to {settings.max_defaults_length}
+                bytes and cannot be exceeded.
+            """.strip(),
+        ),
     ] = None
-    client: Optional[str] = None
-    rootfs_size_mb: Optional[
-        Annotated[
-            int,
-            Field(
-                default=None,
-                ge=1,
-                le=settings.max_custom_rootfs_size_mb,
-                description="Ability to specify a custom CONFIG_TARGET_ROOTFS_PARTSIZE for the\n"
-                "resulting image. Attaching this optional parameter will cause\n"
-                "ImageBuilder to build a rootfs with that size in MB.",
-            ),
-        ]
+    rootfs_size_mb: Annotated[
+        int | None,
+        Field(
+            ge=1,
+            le=settings.max_custom_rootfs_size_mb,
+            examples=[256],
+            description="""
+                Ability to specify a custom `CONFIG_TARGET_ROOTFS_PARTSIZE`
+                for the resulting image. Attaching this optional parameter
+                will cause ImageBuilder to build a rootfs with that size
+                in MB.
+            """.strip(),
+        ),
+    ] = None
+    repositories: Annotated[
+        dict[str, str],
+        Field(
+            description="""
+                Additional repositories for user packages.
+            """.strip()
+        ),
+    ] = {}
+    repository_keys: Annotated[
+        list[str],
+        Field(
+            description="""
+                    Verfication keys for the additional repositories.
+                """.strip(),
+        ),
+    ] = []
+    client: Annotated[
+        str | None,
+        Field(
+            examples=["luci/git-22.073.39928-701ea94"],
+            description="""
+                Client name and version that requests the image,
+            """.strip(),
+        ),
     ] = None
-    diff_packages: Optional[bool] = False
-    repositories: Optional[dict[str, str]] = {}
-    repository_keys: Optional[list[str]] = []