From 7a1cb7cff74429cb39feb2d40df3da8782a2f49b Mon Sep 17 00:00:00 2001 From: Gersona Date: Wed, 27 Nov 2024 18:50:56 +0300 Subject: [PATCH] update OpenAPI documentation --- weblate/api/serializers.py | 46 ++++++++++++++--------------- weblate/api/views.py | 59 +++++++++++++++++++++++++------------- 2 files changed, 62 insertions(+), 43 deletions(-) diff --git a/weblate/api/serializers.py b/weblate/api/serializers.py index d51d78765e48..cac6d70c4d34 100644 --- a/weblate/api/serializers.py +++ b/weblate/api/serializers.py @@ -1538,7 +1538,7 @@ class MetricsSerializer(ReadOnlySerializer): ) ] ) -class ServiceConfigSerializer(serializers.Serializer): +class SingleServiceConfigSerializer(serializers.Serializer): service = serializers.CharField() configuration = serializers.DictField() @@ -1553,13 +1553,10 @@ class ServiceConfigSerializer(serializers.Serializer): }, request_only=False, response_only=True, - ), - OpenApiExample( - "Error message", value={"errors": "Error message"}, status_codes=[400] - ), + ) ] ) -class ProjectMachinerySettingsSerializer(ReadOnlySerializer): +class ProjectMachinerySettingsSerializer(serializers.Serializer): def to_representation(self, instance: Project): return dict(instance.machinery_settings) @@ -1571,20 +1568,23 @@ def map_serializer(self, auto_schema: AutoSchema, direction): return build_object_type(properties={"service_name": build_basic_type(dict)}) -EditServiceSettingsResponseSerializer = { - 200: inline_serializer( - "Simple message serializer", - fields={ - "message": serializers.CharField(), - }, - ), - 201: inline_serializer( - "Simple message serializer", - fields={ - "message": serializers.CharField(), - }, - ), - 400: inline_serializer( - "Simple error message serializer", fields={"errors": serializers.CharField()} - ), -} +def edit_service_settings_response_serializer(*codes) -> int: + _serializers = { + 200: inline_serializer( + "Simple message serializer", + fields={ + "message": serializers.CharField(), + }, + ), + 201: inline_serializer( + "Simple message serializer", + fields={ + "message": serializers.CharField(), + }, + ), + 400: inline_serializer( + "Simple error message serializer", + fields={"errors": serializers.CharField()}, + ), + } + return {code: _serializers[code] for code in codes} diff --git a/weblate/api/views.py b/weblate/api/views.py index 606227703e9e..a28971c03e1c 100644 --- a/weblate/api/views.py +++ b/weblate/api/views.py @@ -58,7 +58,6 @@ ChangeSerializer, ComponentListSerializer, ComponentSerializer, - EditServiceSettingsResponseSerializer, FullUserSerializer, GroupSerializer, LabelSerializer, @@ -77,13 +76,14 @@ ScreenshotCreateSerializer, ScreenshotFileSerializer, ScreenshotSerializer, - ServiceConfigSerializer, + SingleServiceConfigSerializer, StatisticsSerializer, TranslationSerializer, UnitSerializer, UnitWriteSerializer, UploadRequestSerializer, UserStatisticsSerializer, + edit_service_settings_response_serializer, get_reverse_kwargs, ) from weblate.auth.models import AuthenticatedHttpRequest, Group, Role, User @@ -1015,11 +1015,28 @@ def file(self, request: Request, **kwargs): name=instance.slug, ) - @extend_schema(responses=ProjectMachinerySettingsSerializer, methods=["GET"]) @extend_schema( - request=ServiceConfigSerializer, - responses=EditServiceSettingsResponseSerializer, - methods=["POST", "PATCH", "PUT"], + responses=ProjectMachinerySettingsSerializer, + methods=["GET"], + description="List machinery settings for a project.", + ) + @extend_schema( + request=SingleServiceConfigSerializer, + responses=edit_service_settings_response_serializer(201, 400), + methods=["POST"], + description="Install a new machinery service", + ) + @extend_schema( + request=SingleServiceConfigSerializer, + responses=edit_service_settings_response_serializer(200, 400), + methods=["PATCH"], + description="Partially update a single service. Leave configuration blank to remove the service", + ) + @extend_schema( + request=ProjectMachinerySettingsSerializer, + responses=edit_service_settings_response_serializer(200, 400), + methods=["PUT"], + description="Replace configuration for all services.", ) @action(detail=True, methods=["get", "post", "patch", "put"]) def machinery_settings(self, request: Request, **kwargs): @@ -1062,21 +1079,22 @@ def machinery_settings(self, request: Request, **kwargs): {"message": f"Service removed: {service.name}"}, status=HTTP_200_OK, ) - # POST - if service_name in project.machinery_settings: + + if request.method == "POST": + if service_name in project.machinery_settings: + return Response( + {"errors": ["Service already exists"]}, + status=HTTP_400_BAD_REQUEST, + ) + + project.machinery_settings[service_name] = configuration + project.save(update_fields=["machinery_settings"]) return Response( - {"errors": ["Service already exists"]}, - status=HTTP_400_BAD_REQUEST, + {"message": f"Service installed: {service.name}"}, + status=HTTP_201_CREATED, ) - project.machinery_settings[service_name] = configuration - project.save(update_fields=["machinery_settings"]) - return Response( - {"message": f"Service installed: {service.name}"}, - status=HTTP_201_CREATED, - ) - - if request.method == "PUT": + elif request.method == "PUT": # replace all service configuration valid_configurations: dict[str, dict] = {} for service_name, configuration in request.data.items(): @@ -1098,9 +1116,10 @@ def machinery_settings(self, request: Request, **kwargs): status=HTTP_201_CREATED, ) - # get request + # GET method return Response( - data=ProjectMachinerySettingsSerializer(project).data, status=HTTP_200_OK + data=ProjectMachinerySettingsSerializer(project).data, + status=HTTP_200_OK, )