docs: org endpoint docstrings

src/organisation/router.py

@@ -58,6 +58,9 @@ router = APIRouter(
 	            status.HTTP_401_UNAUTHORIZED: {"description": "Not authorised. Must be org root user."},
             })
 async def get_org_by_id(org_model: org_model_root_claim_query_dependency):
+	"""
+	Returns organisation details including key member email addresses
+	"""
 	response = {
 		"name": org_model.name,
 		"status": org_model.status,
@@ -81,13 +84,17 @@ async def get_org_by_id(org_model: org_model_root_claim_query_dependency):
 	             status.HTTP_409_CONFLICT: {"description": "Organisation with this name already exists."},
              })
 async def create_org(db: db_dependency, user_model: user_model_claims_dependency, request_model: OrgPostOrgRequest):
+	"""
+	Creates a new organisation with optional questionnaire (to be completed or submitted).
+	ALl organisations are given the "partial" status on creation. See update_questionnaire() for more details.
+	"""
 	if request_model.intake_questionnaire:
 		intake_questionnaire = request_model.intake_questionnaire.model_dump()
 	else:
 		intake_questionnaire = None
 	org_model = Org(name=request_model.name, intake_questionnaire=intake_questionnaire)
 
-	org_model.status = "partial"  # Status is always set to partial at first, see update_questionnaire() doc
+	org_model.status = "partial"
 
 	db.add(org_model)
 	try:
@@ -145,6 +152,9 @@ async def update_questionnaire(db: db_dependency, org_model: org_model_root_clai
 	              status.HTTP_401_UNAUTHORIZED: {"description": "Not authorised. Must be super admin."},
               })
 async def update_status(db: db_dependency, org_model: org_model_body_dependency, su: super_admin_dependency, request_model: OrgPatchStatusRequest):
+	"""
+	Sets an organisation's status. This is the endpoint for approving or denying an organisation after reviewing the questionnaire.
+	"""
 	org_model.status = request_model.status
 	db.flush()
 	response = OrgPatchStatusResponse(**org_model.__dict__)
@@ -162,10 +172,13 @@ async def update_status(db: db_dependency, org_model: org_model_body_dependency,
 	            status.HTTP_401_UNAUTHORIZED: {"description": "Not authorised. Must be org root user."},
             })
 async def get_users(org_model: org_model_root_claim_query_dependency):
-		return {"users": [user.email for user in org_model.user_rel]}
+	"""
+	Returns a list of the email addresses of all users of the organisation.
+	"""
+	return {"users": [user.email for user in org_model.user_rel]}
 
 
-@router.post("/users",
+@router.post("/user",
              summary="Add user to the organisation.",
              status_code=status.HTTP_200_OK,
              response_model=OrgPostUserResponse,
@@ -176,6 +189,9 @@ async def get_users(org_model: org_model_root_claim_query_dependency):
 	             status.HTTP_409_CONFLICT: {"description": "User is already a member of the organisation."},
              })
 async def add_user_to_org(db: db_dependency, org_model: org_model_root_claim_body_dependency, user_model: user_model_body_dependency, request_model: OrgPostUserRequest):
+	"""
+	Adds a user to the organisation.
+	"""
 	if user_model in org_model.user_rel:
 		raise ConflictException(message="User already a part of this organisation")
 	org_model.user_rel.append(user_model)
@@ -194,6 +210,9 @@ async def add_user_to_org(db: db_dependency, org_model: org_model_root_claim_bod
 	               status.HTTP_422_UNPROCESSABLE_CONTENT: {"description": "Org ID missing or invalid."},
                })
 async def delete_organisation_by_id(db: db_dependency, org_model: org_model_body_dependency, su: super_admin_dependency, request_model: OrgDeleteOrgRequest):
+	"""
+	Removes an organisation from the hub.
+	"""
 	db.delete(org_model)
 	db.commit()
 
@@ -208,6 +227,9 @@ async def delete_organisation_by_id(db: db_dependency, org_model: org_model_body
 	              status.HTTP_401_UNAUTHORIZED: {"description": "Not authorised. Must be super admin."},
               })
 async def update_root_user(db: db_dependency, org_model: org_model_body_dependency, user_model: user_model_body_dependency, su: super_admin_dependency, request_model: OrgPatchRootRequest):
+	"""
+	Promotes an existing organisation user to the root user, giving them full control of the org.
+	"""
 	if user_model not in org_model.user_rel:
 		raise UnauthorizedException(message="This user does not belong to your organisation.")
 	org_model.root_user_rel = user_model
@@ -227,6 +249,9 @@ async def update_root_user(db: db_dependency, org_model: org_model_body_dependen
 	            status.HTTP_401_UNAUTHORIZED: {"description": "Not authorised. Must be org root user."},
             })
 async def get_org_groups(org_model: org_model_root_claim_query_dependency):
+	"""
+	Returns a list of the names of all IAM groups created by the organisation.
+	"""
 	return {"groups": [group.name for group in org_model.group_rel]}
 
 
@@ -239,6 +264,9 @@ async def get_org_groups(org_model: org_model_root_claim_query_dependency):
 	               status.HTTP_422_UNPROCESSABLE_CONTENT: {"description": "Invalid data in request."},
                })
 async def remove_user_from_org(db: db_dependency, org_model: org_model_root_claim_body_dependency, user_model: user_model_body_dependency, request_model: OrgDeleteUserRequest):
+	"""
+	Revokes a user's membership in an organisation.
+	"""
 	if user_model not in org_model.user_rel:
 		return
 
@@ -256,6 +284,9 @@ async def remove_user_from_org(db: db_dependency, org_model: org_model_root_clai
 	            status.HTTP_401_UNAUTHORIZED: {"description": "Not authorised. Must be org root user."},
             })
 async def get_contact(org_model: org_model_root_claim_query_dependency, contact_type: Annotated[ContactType, Query(description="Must be billing|security|owner")]):
+	"""
+	Gets full details for a contact point at an organisation.
+	"""
 	match contact_type:
 		case "billing":
 			contact_model = org_model.billing_contact_rel
@@ -285,6 +316,9 @@ async def get_contact(org_model: org_model_root_claim_query_dependency, contact_
 	              status.HTTP_401_UNAUTHORIZED: {"description": "Not authorised. Must be org root user."},
               })
 async def update_contact(db: db_dependency, org_model: org_model_root_claim_body_dependency, request_model: OrgPatchContactRequest):
+	"""
+	Updates details for a contact point at an organisation.
+	"""
 	match request_model.contact_type:
 		case "billing":
 			contact_model = org_model.billing_contact_rel