From aa7dc465334840b796b0e69318fb860b54d41df3 Mon Sep 17 00:00:00 2001 From: luxferre Date: Thu, 28 May 2026 15:25:29 +0100 Subject: [PATCH 1/3] docs: service router details --- src/main.py | 6 +++++- src/service/router.py | 22 +++++++++++++++++----- 2 files changed, 22 insertions(+), 6 deletions(-) diff --git a/src/main.py b/src/main.py index 3995edf..0092af0 100644 --- a/src/main.py +++ b/src/main.py @@ -31,7 +31,11 @@ tags_metadata = [ { "name": "User", "description": "User related operations, includes getting information about the current user", - } + }, + { + "name": "Service", + "description": "Services related operations, includes registering services and reissuing API keys", + }, ] diff --git a/src/service/router.py b/src/service/router.py index bf01a87..b9d664f 100644 --- a/src/service/router.py +++ b/src/service/router.py @@ -26,16 +26,22 @@ router = APIRouter( prefix="/service", ) -@router.get("/", response_model=ServiceGetServiceResponse) +@router.get("/", status_code=status.HTTP_200_OK, response_model=ServiceGetServiceResponse) 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. + """ permission_models = db.query(Service).all() return {"services": permission_models} -@router.post("/", response_model=ServicePostServiceResponse) -async def register_service(db: db_dependency, su: super_admin_dependency, service_request: ServicePostServiceRequest): +@router.post("/", status_code=status.HTTP_200_OK, response_model=ServicePostServiceResponse) +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. + """ key = generate_api_key() - service_model = Service(name=service_request.name, api_key=key) + service_model = Service(name=request_model.name, api_key=key) db.add(service_model) try: @@ -48,8 +54,11 @@ async def register_service(db: db_dependency, su: super_admin_dependency, servic db.commit() return {"service": response} -@router.patch("/key", response_model=ServicePatchKeyResponse) +@router.patch("/key", status_code=status.HTTP_200_OK, response_model=ServicePatchKeyResponse) 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. + """ key = generate_api_key() service_model.api_key = key @@ -60,5 +69,8 @@ async def regenerate_api_key(db: db_dependency, su: super_admin_dependency, serv @router.delete("/", status_code=status.HTTP_204_NO_CONTENT) 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. + """ db.delete(service_model) db.commit() From b3085e85fd67b3a956b1097f5a2cf89a2d4b7b87 Mon Sep 17 00:00:00 2001 From: luxferre Date: Thu, 28 May 2026 15:30:39 +0100 Subject: [PATCH 2/3] 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. From 01c49ca34cf5f24ef1c8d55c501d18f15642f240 Mon Sep 17 00:00:00 2001 From: luxferre Date: Thu, 28 May 2026 15:41:10 +0100 Subject: [PATCH 3/3] docs: module template docstrings --- src/_module_template/config.py | 6 ++---- src/_module_template/constants.py | 6 ++---- src/_module_template/dependencies.py | 11 +++-------- src/_module_template/exceptions.py | 5 ++--- src/_module_template/models.py | 8 +++++--- src/_module_template/router.py | 11 +++++------ src/_module_template/schemas.py | 9 +++++---- src/_module_template/service.py | 10 ++-------- src/_module_template/utils.py | 10 +--------- 9 files changed, 27 insertions(+), 49 deletions(-) diff --git a/src/_module_template/config.py b/src/_module_template/config.py index 4be170e..45d3182 100644 --- a/src/_module_template/config.py +++ b/src/_module_template/config.py @@ -1,7 +1,5 @@ """ -Configurations for +Configurations for the module -Configurations: - - List: Description - - Configs: Description +Exports: """ \ No newline at end of file diff --git a/src/_module_template/constants.py b/src/_module_template/constants.py index e1df957..cc72009 100644 --- a/src/_module_template/constants.py +++ b/src/_module_template/constants.py @@ -1,7 +1,5 @@ """ -Constants and error codes for +Constants for the module -Constants: - - List: Description - - Consts: Description +Exports: """ \ No newline at end of file diff --git a/src/_module_template/dependencies.py b/src/_module_template/dependencies.py index 7447aaf..71750bc 100644 --- a/src/_module_template/dependencies.py +++ b/src/_module_template/dependencies.py @@ -1,11 +1,6 @@ """ -Router dependencies for +Dependencies related to the module -Classes: - - List: Description - - Classes: Description - -Functions: - - List: Description - - Functions: Description +Exports: + - : : """ \ No newline at end of file diff --git a/src/_module_template/exceptions.py b/src/_module_template/exceptions.py index 5debbb4..402940a 100644 --- a/src/_module_template/exceptions.py +++ b/src/_module_template/exceptions.py @@ -1,7 +1,6 @@ """ -Module specific exceptions for +Exceptions related to the modules Exceptions: - - List: Description - - Exceptions: Description + - : Details e.g. optional params """ \ No newline at end of file diff --git a/src/_module_template/models.py b/src/_module_template/models.py index 6d2494b..d03c882 100644 --- a/src/_module_template/models.py +++ b/src/_module_template/models.py @@ -1,7 +1,9 @@ """ -Database models for +Database models for the module Models: - - List: Description - - Models: Description + - : + - + - + - """ \ No newline at end of file diff --git a/src/_module_template/router.py b/src/_module_template/router.py index 2eb8569..d96d7ee 100644 --- a/src/_module_template/router.py +++ b/src/_module_template/router.py @@ -1,13 +1,12 @@ """ -Router endpoints for +Router endpoints for the module -Endpoints: - - List: Description - - Endpoints: Description +Exports: + - router: fastapi.APIRouter """ from fastapi import APIRouter -_router = APIRouter( +router = APIRouter( tags=[""], -) \ No newline at end of file +) diff --git a/src/_module_template/schemas.py b/src/_module_template/schemas.py index a074c75..71cfc07 100644 --- a/src/_module_template/schemas.py +++ b/src/_module_template/schemas.py @@ -1,7 +1,8 @@ """ -Pydantic models for +Pydantic models for the module -Models: - - List: Description - - Models: Description +Models follow the nomenclature of: +- Sub-models: "Schema" +- Mixins: "Mixin" +- Models: "" ie "" """ \ No newline at end of file diff --git a/src/_module_template/service.py b/src/_module_template/service.py index 7365fa9..139a237 100644 --- a/src/_module_template/service.py +++ b/src/_module_template/service.py @@ -1,11 +1,5 @@ """ -Module specific business logic for +Module specific business logic for the module -Classes: - - List: Description - - Classes: Description - -Functions: - - List: Description - - Functions: Description +Exports: """ \ No newline at end of file diff --git a/src/_module_template/utils.py b/src/_module_template/utils.py index f2da15a..4e99ff6 100644 --- a/src/_module_template/utils.py +++ b/src/_module_template/utils.py @@ -1,11 +1,3 @@ """ -Non-business logic reusable functions and classes for - -Classes: - - List: Description - - Classes: Description - -Functions: - - List: Description - - Functions: Description +Non-business logic reusable functions and classes for the module """ \ No newline at end of file