Use django-rest-swagger for API documentation.

modoboa/admin/api.py

@@ -103,7 +103,36 @@ class AccountViewSet(viewsets.ModelViewSet):
 
 
 class AliasViewSet(viewsets.ModelViewSet):
-    """ViewSet for Alias."""
+    """ViewSet for Alias.
+
+    ---
+    create:
+        serializer: modoboa.admin.serializers.AliasSerializer
+        parameters:
+            - name: recipients
+              description: recipient(s) of the alias
+              required: true
+              type: array[string]
+              paramType: form
+
+    update:
+        serializer: modoboa.admin.serializers.AliasSerializer
+        parameters:
+            - name: recipients
+              description: recipient(s) of the alias
+              required: true
+              type: array[string]
+              paramType: form
+
+    partial_update:
+        serializer: modoboa.admin.serializers.AliasSerializer
+        parameters:
+            - name: recipients
+              description: recipient(s) of the alias
+              required: true
+              type: array[string]
+              paramType: form
+    """
 
     permission_classes = [IsAuthenticated, DjangoModelPermissions, ]
     serializer_class = serializers.AliasSerializer

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

@@ -49,6 +49,7 @@ INSTALLED_APPS = (
     'django.contrib.staticfiles',
     'reversion',
     'rest_framework.authtoken',
+    'rest_framework.swagger,
 {% if devmode %}    'djangobower',{% endif %}
 )
 
@@ -160,6 +161,17 @@ REST_FRAMEWORK = {
     )
 }
 
+SWAGGER_SETTINGS = {
+    "is_authenticated": False,
+    "api_version": "1.0",
+    "exclude_namespaces": [],
+    "info": {
+        "contact": "contact@modoboa.com",
+        "description": ("Modoboa API, requires a valid token."),
+        "title": "Modoboa API",
+    }
+}
+
 # Modoboa settings
 #MODOBOA_CUSTOM_LOGO = os.path.join(MEDIA_URL, "custom_logo.png")
 

modoboa/urls.py

@@ -34,6 +34,7 @@ parameters.apply_to_django_settings()
 urlpatterns += patterns(
     "",
     ("^api/v1/", include("modoboa.urls_api", namespace="external_api")),
+    url("^docs/api/", include('rest_framework_swagger.urls')),
 )
 
 if 'modoboa.demo' in settings.INSTALLED_APPS:

requirements.txt

@@ -11,5 +11,6 @@ django-passwords==0.3.4
 rfc6266
 progressbar==2.3
 djangorestframework==3.3.1
+django-rest-swagger==0.3.5
 django-subcommand2==0.1.1