Improved API doc.

modoboa/admin/models/domain.py

@@ -80,15 +80,15 @@ class Domain(mixins.MessageLimitMixin, AdminObject):
         self.old_dkim_key_length = self.dkim_key_length
 
     @property
-    def domainalias_count(self):
+    def domainalias_count(self) -> int:
         return self.domainalias_set.count()
 
     @property
-    def mailbox_count(self):
+    def mailbox_count(self) -> int:
         return self.mailbox_set.count()
 
     @property
-    def mbalias_count(self):
+    def mbalias_count(self) -> int:
         return self.alias_set.filter(internal=False).count()
 
     @property
@@ -150,7 +150,7 @@ class Domain(mixins.MessageLimitMixin, AdminObject):
         return False
 
     @cached_property
-    def dns_status(self):
+    def dns_status(self) -> dict:
         """Return information about current DNS status."""
         if not self.enable_dns_checks or self.uses_a_reserved_tld:
             return {"checks": "disabled"}

modoboa/admin/serializers.py

@@ -1,5 +1,7 @@
 """Admin serializers."""
 
+from typing import List
+
 from django.conf import settings
 from django.contrib.auth import password_validation
 from django.core.exceptions import ValidationError
@@ -200,7 +202,7 @@ class AccountSerializer(serializers.ModelSerializer):
         """Return role."""
         return account.role
 
-    def get_domains(self, account):
+    def get_domains(self, account) -> List[str]:
         """Return domains administered by this account."""
         if account.role not in ["DomainAdmins", "Resellers"]:
             return []

modoboa/core/serializers.py

@@ -138,7 +138,7 @@ class LogSerializer(serializers.ModelSerializer):
         model = models.Log
         fields = ("date_created", "message", "level", "logger")
 
-    def get_date_created(self, log):
+    def get_date_created(self, log) -> str:
         return formats.date_format(log.date_created, "SHORT_DATETIME_FORMAT")
 
 

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)

modoboa/urls.py

@@ -60,12 +60,21 @@ if extra_routes:
 
 # API urls
 urlpatterns += [
-    path('docs/openapi.json', SpectacularJSONAPIView.as_view(), name='schema'),
-    path('docs/api/',
-         SpectacularSwaggerView.as_view(url_name='schema'),
-         name='docs-index'),
-    path('docs/api/redoc/', SpectacularRedocView.as_view(url_name='schema'),
-         name='redoc'),
+    path('api/schema-v1/',
+         SpectacularJSONAPIView.as_view(api_version="v1"), name='schema-v1'),
+    path('api/schema-v1/swagger/',
+         SpectacularSwaggerView.as_view(url_name='schema-v1'),
+         name='docs-index-v1'),
+    path('api/schema-v1/redoc/',
+         SpectacularRedocView.as_view(url_name='schema-v1')),
+
+    path('api/schema-v2/',
+         SpectacularJSONAPIView.as_view(api_version="v2"), name='schema-v2'),
+    path('api/schema-v2/swagger/',
+         SpectacularSwaggerView.as_view(url_name='schema-v2'),
+         name='docs-index-v2'),
+    path('api/schema-v2/redoc/',
+         SpectacularRedocView.as_view(url_name='schema-v2')),
     path('api/v1/', include("modoboa.urls_api", namespace="v1")),
     path('api/v2/', include("modoboa.urls_api", namespace="v2")),
 ]