From 53e01033c4386e7e032ed70b7d2c389d1b9f2f51 Mon Sep 17 00:00:00 2001 From: luxferre Date: Fri, 29 May 2026 10:40:24 +0100 Subject: [PATCH] docs: org endpoint docstrings --- src/organisation/router.py | 40 +++++++++++++++++++++++++++++++++++--- 1 file changed, 37 insertions(+), 3 deletions(-) diff --git a/src/organisation/router.py b/src/organisation/router.py index 37b46d4..1d7f3d3 100644 --- a/src/organisation/router.py +++ b/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