fix: apply GSDFC docstring conformance, add minimal annotations to unannotated params (pydoclint zero); refresh lib/MCP docs

openapi_first/app.py

@@ -34,6 +34,7 @@ Notes:
 
 import os
 import re
+from typing import Any
 
 from fastapi import FastAPI
 
@@ -105,8 +106,8 @@ class OpenAPIFirstApp(FastAPI):
         self,
         *,
         openapi_path: str,
-        routes_module,
-        **fastapi_kwargs,
+        routes_module: Any,
+        **fastapi_kwargs: Any,
     ):
         """
         Initialize the application.
@@ -115,7 +116,7 @@ class OpenAPIFirstApp(FastAPI):
             openapi_path (str):
                 Filesystem path to the OpenAPI 3.x specification file. This
                 specification is treated as the authoritative API contract.
-            routes_module (module):
+            routes_module (Any):
                 Python module containing handler functions whose names correspond
                 exactly to OpenAPI ``operationId`` values.
             **fastapi_kwargs (Any):

openapi_first/binder.py

@@ -40,23 +40,23 @@ from .errors import MissingOperationHandler
 
 
 def bind_routes(
-    app,
+    app: Any,
     spec: dict,
-    routes_module,
+    routes_module: Any,
     security_deps: dict[str, list[Any]] | None = None,
 ) -> None:
     """
     Bind OpenAPI operations to FastAPI routes.
 
     Args:
-        app (fastapi.FastAPI):
+        app (Any):
             The FastAPI application instance to which routes will be added.
         spec (dict):
             Parsed OpenAPI 3.x specification dictionary.
-        routes_module (module):
+        routes_module (Any):
             Python module containing handler functions. Each handler's name MUST
             exactly match an OpenAPI `operationId`.
-        security_deps (dict | None):
+        security_deps (dict[str, list[Any]] | None):
             Optional mapping of ``METHOD:/path`` → ``list[Depends(...)]``
             generated from the spec's ``securitySchemes`` and per-operation
             ``security`` fields.

openapi_first/cli.py

@@ -1,10 +1,8 @@
 """
+# Summary
+
 Command-line interface for FastAPI OpenAPI-first scaffolding utilities.
 
----
-
-## Summary
-
 This CLI bootstraps OpenAPI-first FastAPI applications from versioned,
 bundled templates packaged with the library.
 """

openapi_first/client.py

@@ -98,9 +98,9 @@ class OpenAPIClient:
         Args:
             spec (dict[str, Any]):
                 Parsed OpenAPI 3.x specification.
-            base_url (str, optional):
+            base_url (str | None):
                 Base URL of the target service. If omitted, the first entry in the OpenAPI `servers` list is used.
-            client (httpx.Client, optional):
+            client (httpx.Client | None):
                 Optional preconfigured httpx client instance.
 
         Raises:

openapi_first/codegen_routes.py

@@ -1,4 +1,6 @@
 """
+# Summary
+
 Route handler code generation from OpenAPI specifications.
 
 This module generates Python route handler stubs from an OpenAPI 3.x
@@ -39,15 +41,15 @@ def generate_routes(
     and ``/pets/{id}`` both group under ``pets``).
 
     Args:
-        spec_path:
+        spec_path (Path):
             Path to the OpenAPI specification file (YAML or JSON).
-        output_dir:
+        output_dir (Path):
             Directory where the generated route files are written.
             Created automatically if it does not exist.
-        use_models:
+        use_models (bool, optional):
             If ``True``, import Pydantic models from *models_module*
             for request-body schemas referenced via ``$ref``.
-        models_module:
+        models_module (str, optional):
             Dotted Python module path from which to import models
             (e.g. ``"models"``, ``"app.models"``).
 

openapi_first/errors.py

@@ -63,7 +63,7 @@ class MissingOperationHandler(OpenAPIFirstError):
                 The HTTP path declared in the OpenAPI specification.
             method (str):
                 The HTTP method (as declared in the OpenAPI spec).
-            operation_id (str, optional):
+            operation_id (str | None):
                 The operationId declared in the OpenAPI spec, if present.
         """
         if operation_id:

openapi_first/security.py

@@ -1,9 +1,12 @@
 """
+# Summary
+
 OpenAPI security scheme parsing and auto-generated auth dependencies.
 
-Reads `securitySchemes` and per-operation `security` from an OpenAPI spec,
-resolves `{ENV_VAR}` placeholders in `x-` extension fields, and generates
-FastAPI dependencies for token validation (e.g., Bearer JWT introspection).
+This module reads `securitySchemes` and per-operation `security` from an
+OpenAPI spec, resolves `{ENV_VAR}` placeholders in `x-` extension fields,
+and generates FastAPI dependencies for token validation (e.g., Bearer JWT
+introspection).
 """
 
 import os