From b3085e85fd67b3a956b1097f5a2cf89a2d4b7b87 Mon Sep 17 00:00:00 2001
From: luxferre <chris@sr2.uk>
Date: Thu, 28 May 2026 15:30:39 +0100
Subject: [PATCH] docs: service router response details

---
 src/service/router.py | 21 +++++++++++++++++----
 1 file changed, 17 insertions(+), 4 deletions(-)

diff --git a/src/service/router.py b/src/service/router.py
index b9d664f..e05a92e 100644
--- a/src/service/router.py
+++ b/src/service/router.py
@@ -26,7 +26,10 @@ router = APIRouter(
 	prefix="/service",
 )
 
-@router.get("/", status_code=status.HTTP_200_OK, 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.
@@ -35,7 +38,11 @@ async def get_all_services(db: db_dependency, org_model: org_model_root_claim_qu
 
 	return {"services": permission_models}
 
-@router.post("/", status_code=status.HTTP_200_OK, response_model=ServicePostServiceResponse)
+@router.post("/", status_code=status.HTTP_200_OK, response_model=ServicePostServiceResponse, responses={
+	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.
@@ -54,7 +61,10 @@ async def register_service(db: db_dependency, su: super_admin_dependency, reques
 	db.commit()
 	return {"service": response}
 
-@router.patch("/key", status_code=status.HTTP_200_OK, 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.
@@ -67,7 +77,10 @@ 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.