Improved API doc.

modoboa/parameters/serializers.py

@@ -0,0 +1,36 @@
+"""Parameters serializers."""
+
+from rest_framework import serializers
+
+
+class ApplicationSerializer(serializers.Serializer):
+    """Application serializer."""
+
+    name = serializers.CharField()
+    label = serializers.CharField()
+
+
+class ParameterChoiceSerializer(serializers.Serializer):
+    """Parameter choice serializer."""
+
+    text = serializers.CharField()
+    value = serializers.CharField()
+
+
+class ParameterSerializer(serializers.Serializer):
+    """Parameter serializer."""
+
+    name = serializers.CharField()
+    label = serializers.CharField()
+    help_text = serializers.CharField()
+    display = serializers.CharField()
+    widget = serializers.CharField()
+    choices = ParameterChoiceSerializer(many=True)
+
+
+class StructureSerializer(serializers.Serializer):
+    """Structure serializer."""
+
+    name = serializers.CharField()
+    display = serializers.CharField(help_text="Display rule")
+    parameters = ParameterSerializer(many=True)

modoboa/parameters/viewsets.py

@@ -1,8 +1,10 @@
 """Parameters viewsets."""
 
+from drf_spectacular.utils import extend_schema, OpenApiParameter
 from rest_framework import response, viewsets
 from rest_framework.decorators import action
 
+from . import serializers
 from . import tools
 
 
@@ -11,12 +13,14 @@ class ParametersViewSet(viewsets.ViewSet):
 
     lookup_value_regex = r"\w+"
 
+    @extend_schema(responses=serializers.ApplicationSerializer(many=True))
     @action(methods=["get"], detail=False)
     def applications(self, request):
-        """Return application list."""
+        """Return the list of registered applications."""
         applications = tools.registry.get_applications("global")
         return response.Response(applications)
 
+    @extend_schema(responses=serializers.ParameterSerializer(many=True))
     @action(methods=["get"], detail=False)
     def structure(self, request):
         """Return parameter schema."""
@@ -24,14 +28,32 @@ class ParametersViewSet(viewsets.ViewSet):
         data = tools.registry.get_structure("global", app)
         return response.Response(data)
 
-    def retrieve(self, request, pk):
+    @extend_schema(
+        parameters=[
+            OpenApiParameter(
+                name='id', location=OpenApiParameter.PATH,
+                description='A registered application name',
+                type=str, required=True
+            ),
+        ]
+    )
+    def retrieve(self, request, pk: str):
         """Return all parameters for given app."""
         parameters = request.localconfig.parameters.get_values_dict(pk)
         serializer = tools.registry.get_serializer_class("global", pk)(
             parameters)
         return response.Response(serializer.data)
 
-    def update(self, request, pk):
+    @extend_schema(
+        parameters=[
+            OpenApiParameter(
+                name='id', location=OpenApiParameter.PATH,
+                description='A registered application name',
+                type=str, required=True
+            ),
+        ]
+    )
+    def update(self, request, pk: str):
         """Save parameters for given app."""
         serializer = tools.registry.get_serializer_class("global", pk)(
             data=request.data)