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/crud_app/__init__.py

@@ -25,15 +25,15 @@ Scaffolding via CLI
 
 Create a new CRUD example service using the bundled template:
 
-    openapi-first crud_app
+    openapi-first scaffold crud_app
 
 Create the service in a custom directory:
 
-    openapi-first crud_app my-crud-service
+    openapi-first scaffold crud_app my-crud-service
 
 List all available application templates:
 
-    openapi-first --list
+    openapi-first scaffold --list
 
 The CLI copies template files verbatim into the target directory.
 No code is generated or modified beyond the copied scaffold.

openapi_first/templates/crud_app/data.py

@@ -33,7 +33,7 @@ _items: Dict[int, dict] = {
 _next_id = 3
 
 
-def list_items():
+def list_items() -> list[dict]:
     """
     Return all items in the data store.
 
@@ -48,7 +48,7 @@ def list_items():
     return list(_items.values())
 
 
-def get_item(item_id: int):
+def get_item(item_id: int) -> dict:
     """
     Retrieve a single item by ID.
 
@@ -68,7 +68,7 @@ def get_item(item_id: int):
     return _items[item_id]
 
 
-def create_item(payload: dict):
+def create_item(payload: dict) -> dict:
     """
     Create a new item in the data store.
 
@@ -92,7 +92,7 @@ def create_item(payload: dict):
     return item
 
 
-def update_item(item_id: int, payload: dict):
+def update_item(item_id: int, payload: dict) -> dict:
     """
     Replace an existing item in the data store.
 

openapi_first/templates/crud_app/routes.py

@@ -29,7 +29,7 @@ from data import (
 )
 
 
-def list_items():
+def list_items() -> list[dict]:
     """
     List all items.
 
@@ -44,7 +44,7 @@ def list_items():
     return _list_items()
 
 
-def get_item(item_id: int):
+def get_item(item_id: int) -> dict:
     """
     Retrieve a single item by ID.
 
@@ -72,7 +72,7 @@ def get_item(item_id: int):
         raise HTTPException(status_code=404, detail="Item not found")
 
 
-def create_item(payload: dict, response: Response):
+def create_item(payload: dict, response: Response) -> dict:
     """
     Create a new item.
 
@@ -83,7 +83,7 @@ def create_item(payload: dict, response: Response):
     ----------
     payload : dict
         Item attributes excluding the ``id`` field.
-    response : fastapi.Response
+    response : Response
         Response object used to set the HTTP status code.
 
     Returns
@@ -96,7 +96,7 @@ def create_item(payload: dict, response: Response):
     return item
 
 
-def update_item(item_id: int, payload: dict):
+def update_item(item_id: int, payload: dict) -> dict:
     """
     Update an existing item.
 
@@ -126,7 +126,7 @@ def update_item(item_id: int, payload: dict):
         raise HTTPException(status_code=404, detail="Item not found")
 
 
-def delete_item(item_id: int, response: Response):
+def delete_item(item_id: int, response: Response) -> None:
     """
     Delete an existing item.
 
@@ -137,7 +137,7 @@ def delete_item(item_id: int, response: Response):
     ----------
     item_id : int
         Identifier of the item to delete.
-    response : fastapi.Response
+    response : Response
         Response object used to set the HTTP status code.
 
     Returns