feat(api): add swagger support at the root of the API

Content Type for it is application/openapi+json or ?format=openapi

Closes #811

rootfs/api/settings/production.py

@@ -101,6 +101,7 @@
     'jsonfield',
     'rest_framework',
     'rest_framework.authtoken',
+    'rest_framework_swagger',
     # Deis apps
     'api'
 )
@@ -161,6 +162,15 @@
     'EXCEPTION_HANDLER': 'api.exceptions.custom_exception_handler'
 }
 
+SWAGGER_SETTINGS = {
+    'SECURITY_DEFINITIONS': {
+#         'basic': {
+#             'type': 'apiKey'
+#         }
+    },
+}
+
+
 # URLs that end with slashes are ugly
 APPEND_SLASH = False
 

rootfs/api/views.py

@@ -11,9 +11,13 @@
 from rest_framework import mixins, renderers, status
 from rest_framework.exceptions import PermissionDenied, NotFound, AuthenticationFailed
 from rest_framework.permissions import IsAuthenticated
+from rest_framework.schemas import SchemaGenerator
 from rest_framework.response import Response
 from rest_framework.viewsets import GenericViewSet
 from rest_framework.authtoken.models import Token
+from rest_framework.decorators import api_view, renderer_classes
+from rest_framework.renderers import CoreJSONRenderer
+from rest_framework_swagger.renderers import OpenAPIRenderer
 
 from api import authentication, models, permissions, serializers, viewsets
 from api.models import AlreadyExists, ServiceUnavailable, DeisException, UnprocessableEntity
@@ -23,6 +27,13 @@
 logger = logging.getLogger(__name__)
 
 
+@api_view()
+@renderer_classes([OpenAPIRenderer, CoreJSONRenderer])
+def schema_view(request):
+    generator = SchemaGenerator(title='Deis Workflow Controller API')
+    return Response(generator.get_schema(request=request))
+
+
 class ReadinessCheckView(View):
     """
     Simple readiness check view to determine DB connection / query.
@@ -543,6 +554,7 @@ class AppPermsViewSet(BaseDeisViewSet):
     """RESTful views for sharing apps with collaborators."""
 
     model = models.App  # models class
+    serializer_class = serializers.UserSerializer
     perm = 'use_app'    # short name for permission
 
     def get_queryset(self):

rootfs/deis/urls.py

@@ -7,10 +7,10 @@
 
 
 from django.conf.urls import include, url
-from api.views import LivenessCheckView
-from api.views import ReadinessCheckView
+from api.views import LivenessCheckView, ReadinessCheckView, schema_view
 
 urlpatterns = [
+    url('^$', schema_view),
     url(r'^healthz$', LivenessCheckView.as_view()),
     url(r'^readiness$', ReadinessCheckView.as_view()),
     url(r'^v2/', include('api.urls')),

rootfs/requirements.txt

@@ -4,6 +4,7 @@ Django==1.10.2
 django-cors-middleware==1.3.1
 django-guardian==1.4.6
 djangorestframework==3.4.7
+django-rest-swagger==2.0.6
 docker-py==1.10.3
 gunicorn==19.6.0
 jmespath==0.9.0