docs: add OpenAPI-first wiki (overview, components, use cases for templates/client/codegen, design, security, error handling, testing) and refresh lib docs index

openapi_first/templates/vet_app/__init__.py

@@ -50,11 +50,11 @@ Scaffolding via CLI
 
 Create a new vet clinic service using the bundled template:
 
-    openapi-first vet_app
+    openapi-first scaffold vet_app
 
 Create the service in a custom directory:
 
-    openapi-first vet_app my-vet-clinic
+    openapi-first scaffold vet_app my-vet-clinic
 
 ----------------------------------------------------------------------
 Client Usage Example

openapi_first/templates/vet_app/routes.py

@@ -43,7 +43,6 @@ from data import (
     create_pet as _create_pet,
     update_pet as _update_pet,
     delete_pet as _delete_pet,
-    get_pet as _get_pet,
     list_appointments as _list_appointments,
     get_appointment as _get_appointment,
     create_appointment as _create_appointment,
@@ -57,7 +56,7 @@ from data import (
 # ---------------------------------------------------------------------------
 
 
-def list_parents(limit: int = 20, offset: int = 0):
+def list_parents(limit: int = 20, offset: int = 0) -> dict:
     """List parents (paginated).
 
     Parameters
@@ -76,13 +75,15 @@ def list_parents(limit: int = 20, offset: int = 0):
     return {"total": len(items), "items": items[offset:offset + limit] if limit else items[offset:]}
 
 
-def create_parent(payload: ParentCreate, response: Response):
+def create_parent(payload: ParentCreate, response: Response) -> Parent:
     """Create a parent.
 
     Parameters
     ----------
     payload : ParentCreate
         Parent data excluding the ``id`` field.
+    response : Response
+        Response object used to set the HTTP status code.
 
     Returns
     -------
@@ -94,7 +95,7 @@ def create_parent(payload: ParentCreate, response: Response):
     return parent
 
 
-def get_parent(id: int):
+def get_parent(id: int) -> Parent:
     """Retrieve a single parent by ID.
 
     Parameters
@@ -118,7 +119,7 @@ def get_parent(id: int):
         raise HTTPException(status_code=404, detail="Parent not found")
 
 
-def update_parent(id: int, payload: ParentCreate):
+def update_parent(id: int, payload: ParentCreate) -> Parent:
     """Update an existing parent.
 
     Parameters
@@ -144,13 +145,15 @@ def update_parent(id: int, payload: ParentCreate):
         raise HTTPException(status_code=404, detail="Parent not found")
 
 
-def delete_parent(id: int, response: Response):
+def delete_parent(id: int, response: Response) -> None:
     """Delete an existing parent.
 
     Parameters
     ----------
     id : int
         Identifier of the parent.
+    response : Response
+        Response object used to set the HTTP status code.
 
     Raises
     ------
@@ -212,7 +215,7 @@ def delete_vet(id: int, response: Response):
 # ---------------------------------------------------------------------------
 
 
-def list_treatments():
+def list_treatments() -> list[Treatment]:
     """List treatments (catalogue).
 
     Returns
@@ -298,7 +301,7 @@ def delete_pet(id: int, response: Response):
     response.status_code = 204
 
 
-def upload_pet_photo(id: int, file: UploadFile):
+def upload_pet_photo(id: int, file: UploadFile) -> dict:
     """Upload a pet photo.
 
     Parameters