From ff4d36b4cde01b3c49deb6dde3e8981456ebceea Mon Sep 17 00:00:00 2001 From: luxferre Date: Thu, 28 May 2026 16:03:04 +0100 Subject: [PATCH 1/2] docs: service module endpoint summaries --- src/service/router.py | 59 +++++++++++++++++++++++++++++-------------- 1 file changed, 40 insertions(+), 19 deletions(-) diff --git a/src/service/router.py b/src/service/router.py index e05a92e..6c0bd41 100644 --- a/src/service/router.py +++ b/src/service/router.py @@ -26,10 +26,15 @@ router = APIRouter( prefix="/service", ) -@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"}, -}) + +@router.get("/", + summary="Get all services", + 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. @@ -38,11 +43,16 @@ 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, 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"}, -}) + +@router.post("/", + summary="Register a new service.", + 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. @@ -61,11 +71,17 @@ 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, 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): + +@router.patch("/key", + summary="Regenerate service API 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. """ @@ -77,11 +93,16 @@ 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, 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): + +@router.delete("/", + summary="Remove a service.", + 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. """ From f60d86e91d5f138777a902ef29c08d34ba56fdff Mon Sep 17 00:00:00 2001 From: luxferre Date: Thu, 28 May 2026 16:03:33 +0100 Subject: [PATCH 2/2] docs: doc guidelines in router template --- src/_module_template/router.py | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/src/_module_template/router.py b/src/_module_template/router.py index d96d7ee..c81fc26 100644 --- a/src/_module_template/router.py +++ b/src/_module_template/router.py @@ -3,6 +3,19 @@ Router endpoints for the module Exports: - router: fastapi.APIRouter + +### Router Guidelines ### +- Add responses to decorators +- Add status_codes to decorators +- All endpoints should either return a response object or 204 +- Ensure response_model is declared in the decorator +- All query and path params should have validation and descriptions +- All endpoints should have a docstring (this is used in place of a description) +- All endpoints should have a summary +- All modules should have metadata in main.py +- All exceptions should have a custom definition in exceptions.py +- Dependencies should be used for db model get and validation where possible +- Verify module level docstring is still accurate after updates """ from fastapi import APIRouter