Merge pull request #943 from tonioo/doc/api

Doc: Api

modoboa/admin/api.py

@@ -56,9 +56,12 @@ class AccountViewSet(viewsets.ModelViewSet):
 
     def get_serializer_class(self):
         """Return a serializer."""
-        if self.request.method == "GET":
-            return serializers.AccountSerializer
-        return serializers.WritableAccountSerializer
+        action_dict = {
+            "list": serializers.AccountSerializer,
+            "retrive": serializers.AccountSerializer
+        }
+        return action_dict.get(
+            self.action, serializers.WritableAccountSerializer)
 
     def get_queryset(self):
         """Filter queryset based on current user."""

modoboa/admin/serializers.py

@@ -8,6 +8,7 @@ from rest_framework import serializers
 from passwords import validators
 
 from modoboa.admin import models as admin_models
+from modoboa.core import constants as core_constants
 from modoboa.core import models as core_models
 from modoboa.core import signals as core_signals
 from modoboa.lib import exceptions as lib_exceptions
@@ -154,6 +155,8 @@ class AccountPasswordSerializer(serializers.ModelSerializer):
 class WritableAccountSerializer(AccountSerializer):
     """Serializer to create account."""
 
+    role = serializers.ChoiceField(choices=core_constants.ROLES)
+
     class Meta(AccountSerializer.Meta):
         fields = AccountSerializer.Meta.fields + (
             "password", )
@@ -184,11 +187,12 @@ class WritableAccountSerializer(AccountSerializer):
     def validate(self, data):
         """Check constraints."""
         master_user = data.get("master_user", False)
-        if master_user and data["role"] != "SuperAdmins":
+        role = data.get("role")
+        if master_user and role != "SuperAdmins":
             raise serializers.ValidationError({
                 "master_user": _("Not allowed for this role.")
             })
-        if data["role"] == "SimpleUsers":
+        if role == "SimpleUsers":
             mailbox = data.get("mailbox")
             if mailbox is None:
                 data["mailbox"] = {

modoboa/core/commands/templates/settings.py.tpl

@@ -167,8 +167,12 @@ SWAGGER_SETTINGS = {
     "exclude_namespaces": [],
     "info": {
         "contact": "contact@modoboa.com",
-        "description": ("Modoboa API, requires a valid token."),
-        "title": "Modoboa API",
+        "description": (
+            "Modoboa API, requires a valid token. To obtain a token, login "
+            "as super administrator, go to 'User settings > API' and enable "
+            "API access. Click on 'Update' and wait for page refresh."
+        ),
+        "title": "Modoboa API documentation",
     }
 }
 

requirements.txt

@@ -12,7 +12,7 @@ django-xforwardedfor-middleware
 django-passwords==0.3.10
 rfc6266
 progressbar==2.3
-djangorestframework==3.3.1
+djangorestframework==3.3.3
 django-rest-swagger==0.3.5
 django-subcommand2==0.1.1
 gevent==1.1.1