From 61e186a7274c40e316fd1dbd119db2fcd21f0035 Mon Sep 17 00:00:00 2001
From: luxferre <chris@sr2.uk>
Date: Wed, 10 Jun 2026 16:49:37 +0100
Subject: [PATCH] docs: iam router (incomplete)

Issue: #13
---
 src/iam/router.py | 69 ++++++++++++++++++++++++++++++++++++++++++-----
 test/test_iam.py  |  2 +-
 2 files changed, 63 insertions(+), 8 deletions(-)

diff --git a/src/iam/router.py b/src/iam/router.py
index 9cd0439..55971f6 100644
--- a/src/iam/router.py
+++ b/src/iam/router.py
@@ -102,9 +102,9 @@ async def can_act_on_resource(
 	request_model: IAMCAoRRequest,
 ):
 	"""
-	This endpoint is not meant for the Hub frontend to interact with.
-	Services accessing this endpoint must be already registered within the Hub and been issued an API key.
-	Resource Names have an instance property but permissions do not presently have that level of granularity.
+	This endpoint is not meant for the Hub frontend to interact with.\n
+	Services accessing this endpoint must be already registered within the Hub and been issued an API key.\n
+	Resource Names have an instance property but permissions do not presently have that level of granularity.\n
 	"""
 	response = {
 		"allowed": False,
@@ -150,11 +150,24 @@ async def can_act_on_resource(
 	return response
 
 
-@router.get("/group/permissions", response_model=IAMGetGroupPermissionsResponse)
+@router.get(
+	path="/group/permissions",
+	summary="Gets a list of permissions granted to a group",
+	status_code=status.HTTP_200_OK,
+	response_model=IAMGetGroupPermissionsResponse,
+	responses={
+		status.HTTP_401_UNAUTHORIZED: {
+			"description": "Group does not belong to this organisation"
+		}
+	},
+)
 async def get_group_permissions(
 	group_model: group_model_query_dependency,
 	org_model: org_model_root_claim_query_dependency,
 ):
+	"""
+	Gets a list of permissions granted to the group. Also returns a summary for the org and group.
+	"""
 	if group_model.org_id != org_model.id:
 		raise UnauthorizedException("Group does not belong to this organization")
 	return {
@@ -164,11 +177,24 @@ async def get_group_permissions(
 	}
 
 
-@router.get("/group/users", response_model=IAMGetGroupUsersResponse)
+@router.get(
+	path="/group/users",
+	summary="Gets a list of users assigned to a group",
+	status_code=status.HTTP_200_OK,
+	response_model=IAMGetGroupUsersResponse,
+	responses={
+		status.HTTP_401_UNAUTHORIZED: {
+			"description": "Group does not belong to this organization"
+		},
+	},
+)
 async def get_group_users(
 	group_model: group_model_query_dependency,
 	org_model: org_model_root_claim_query_dependency,
 ):
+	"""
+	Gets a list of users assigned to the group. Also returns a summary for the org and group.
+	"""
 	if group_model.org_id != org_model.id:
 		raise UnauthorizedException("Group does not belong to this organization")
 	return {
@@ -178,12 +204,25 @@ async def get_group_users(
 	}
 
 
-@router.post("/group", response_model=IAMPostGroupResponse)
+@router.post(
+	path="/group",
+	summary="Creates a new group",
+	status_code=status.HTTP_201_CREATED,
+	response_model=IAMPostGroupResponse,
+	responses={
+		status.HTTP_409_CONFLICT: {
+			"description": "Group with this name already exists"
+		},
+	},
+)
 async def create_group(
 	db: db_dependency,
 	org_model: org_model_root_claim_body_dependency,
 	request_model: IAMPostGroupRequest,
 ):
+	"""
+	Creates a new IAM group.
+	"""
 	group_model = Group(name=request_model.name, org_id=org_model.id)
 
 	db.add(group_model)
@@ -200,7 +239,20 @@ async def create_group(
 	return {"group": response}
 
 
-@router.put("/group/permission", response_model=IAMPutGroupPermissionResponse)
+@router.put(
+	path="/group/permission",
+	summary="Grants a permission to a group",
+	status_code=status.HTTP_200_OK,
+	response_model=IAMPutGroupPermissionResponse,
+	responses={
+		status.HTTP_401_UNAUTHORIZED: {
+			"description": "Group does not belong to this organization"
+		},
+		status.HTTP_409_CONFLICT: {
+			"description": "This permission is already granted to this group"
+		},
+	},
+)
 async def add_group_permission(
 	db: db_dependency,
 	group_model: group_model_body_dependency,
@@ -208,6 +260,9 @@ async def add_group_permission(
 	org_model: org_model_root_claim_body_dependency,
 	request_model: IAMPutGroupPermissionRequest,
 ):
+	"""
+	Grants a permission to a group. Returns a list of the permissions in the group as well as a summary for the org and group.
+	"""
 	if group_model.org_id != org_model.id:
 		raise UnauthorizedException("Group does not belong to this organization")
 
diff --git a/test/test_iam.py b/test/test_iam.py
index a8f46f6..5364e87 100644
--- a/test/test_iam.py
+++ b/test/test_iam.py
@@ -280,7 +280,7 @@ async def test_post_group_success(default_client: AsyncClient):
 	resp = await default_client.post(
 		"/iam/group", json={"name": "New Group", "organisation_id": 1}
 	)
-	assert resp.status_code == 200
+	assert resp.status_code == 201
 
 	data = resp.json()