docs: module template docstrings

src/_module_template/config.py

@@ -1,7 +1,5 @@
 """
-Configurations for <this module>
+Configurations for the <this> module
 
-Configurations:
+Exports:
- - List: Description
- - Configs: Description
 """

src/_module_template/constants.py

@@ -1,7 +1,5 @@
 """
-Constants and error codes for <this module>
+Constants for the <this> module
 
-Constants:
+Exports:
- - List: Description
- - Consts: Description
 """

src/_module_template/dependencies.py

@@ -1,11 +1,6 @@
 """
-Router dependencies for <this module>
+Dependencies related to the <this> module
 
-Classes:
+Exports:
- - List: Description
+ - <dep_name>: <return_type>: <description>
- - Classes: Description
-
-Functions:
- - List: Description
- - Functions: Description
 """

src/_module_template/exceptions.py

@@ -1,7 +1,6 @@
 """
-Module specific exceptions for <this module>
+Exceptions related to the <this> modules
 
 Exceptions:
- - List: Description
+ - <ExceptionName>: Details e.g. optional params
- - Exceptions: Description
 """

src/_module_template/models.py

@@ -1,7 +1,9 @@
 """
-Database models for <this module>
+Database models for the <this> module
 
 Models:
- - List: Description
+ - <ModelName>:
- - Models: Description
+  - <normal_columns[FK][PK]>
+  - <orm_relationships>
+  - <calculated_properties>
 """

src/_module_template/router.py

@@ -1,13 +1,12 @@
 """
-Router endpoints for <this module>
+Router endpoints for the <this> module
 
-Endpoints:
+Exports:
- - List: Description
+ - router: fastapi.APIRouter
- - Endpoints: Description
 """
 from fastapi import APIRouter
 
 
-_router = APIRouter(
+router = APIRouter(
 	tags=[""],
 )

src/_module_template/schemas.py

@@ -1,7 +1,8 @@
 """
-Pydantic models for <this module>
+Pydantic models for the <this> module
 
-Models:
+Models follow the nomenclature of:
- - List: Description
+- Sub-models: "<Resource><Opt:>Schema"
- - Models: Description
+- Mixins: "<Attribute>Mixin"
+- Models: "<Module><Method><Resource><Opt:Resource><Direction>" ie ""
 """

src/_module_template/service.py

@@ -1,11 +1,5 @@
 """
-Module specific business logic for <this module>
+Module specific business logic for the <this> module
 
-Classes:
+Exports:
- - List: Description
- - Classes: Description
-
-Functions:
- - List: Description
- - Functions: Description
 """

src/_module_template/utils.py

@@ -1,11 +1,3 @@
 """
-Non-business logic reusable functions and classes for <this module>
+Non-business logic reusable functions and classes for the <this> module
-
-Classes:
- - List: Description
- - Classes: Description
-
-Functions:
- - List: Description
- - Functions: Description
 """

src/main.py

@@ -31,7 +31,11 @@ tags_metadata = [
 	{
 		"name": "User",
 		"description": "User related operations, includes getting information about the current user",
-	}
+	},
+	{
+		"name": "Service",
+		"description": "Services related operations, includes registering services and reissuing API keys",
+	},
 ]
 
 

src/service/router.py

@@ -26,16 +26,29 @@ router = APIRouter(
 	prefix="/service",
 )
 
-@router.get("/", response_model=ServiceGetServiceResponse)
+@router.get("/", status_code=status.HTTP_200_OK, response_model=ServiceGetServiceResponse, responses={
+	status.HTTP_200_OK: {"description": "Successful retrieval from database"},
+	status.HTTP_401_UNAUTHORIZED: {"description": "Unauthorized"},
+})
 async def get_all_services(db: db_dependency, org_model: org_model_root_claim_query_dependency):
+	"""
+	Returns the ID and name of all services registered to the hub.
+	"""
 	permission_models = db.query(Service).all()
 
 	return {"services": permission_models}
 
-@router.post("/", response_model=ServicePostServiceResponse)
+@router.post("/", status_code=status.HTTP_200_OK, response_model=ServicePostServiceResponse, responses={
-async def register_service(db: db_dependency, su: super_admin_dependency, service_request: ServicePostServiceRequest):
+	status.HTTP_200_OK: {"description": "Successfully registered a new service"},
+	status.HTTP_401_UNAUTHORIZED: {"description": "Unauthorized"},
+	status.HTTP_409_CONFLICT: {"description": "Service with this name already exists"},
+})
+async def register_service(db: db_dependency, su: super_admin_dependency, request_model: ServicePostServiceRequest):
+	"""
+	Registers a new service to the hub, generating and returning an API key for it.
+	"""
 	key = generate_api_key()
-	service_model = Service(name=service_request.name, api_key=key)
+	service_model = Service(name=request_model.name, api_key=key)
 
 	db.add(service_model)
 	try:
@@ -48,8 +61,14 @@ async def register_service(db: db_dependency, su: super_admin_dependency, servic
 	db.commit()
 	return {"service": response}
 
-@router.patch("/key", response_model=ServicePatchKeyResponse)
+@router.patch("/key", status_code=status.HTTP_200_OK, response_model=ServicePatchKeyResponse, responses={
+	status.HTTP_200_OK: {"description": "Successful update of API key"},
+	status.HTTP_401_UNAUTHORIZED: {"description": "Unauthorized"},
+})
 async def regenerate_api_key(db: db_dependency, su: super_admin_dependency, service_model: service_model_body_dependency, request_model: ServicePatchKeyRequest):
+	"""
+	Generates and returns a new API key for the service to access the hub.
+	"""
 	key = generate_api_key()
 	service_model.api_key = key
 
@@ -58,7 +77,13 @@ async def regenerate_api_key(db: db_dependency, su: super_admin_dependency, serv
 	db.commit()
 	return {"service": response}
 
-@router.delete("/", status_code=status.HTTP_204_NO_CONTENT)
+@router.delete("/", status_code=status.HTTP_204_NO_CONTENT, responses={
+	status.HTTP_204_NO_CONTENT: {"description": "Successfully removed service from db"},
+	status.HTTP_401_UNAUTHORIZED: {"description": "Unauthorized"},
+})
 async def remove_service(db: db_dependency, service_model: service_model_body_dependency, su: super_admin_dependency, request_model: ServiceDeleteServiceRequest):
+	"""
+	Removes a service from the hub.
+	"""
 	db.delete(service_model)
 	db.commit()