Merge pull request #32 from volCommunity/swagger_versioning

Swagger, Accept header versioning

Author: ojongerius

Pipfile

@@ -12,12 +12,13 @@ whitenoise = "*"
 "django-analytical" = "*"
 djangorestframework = "*"
 "factory-boy" = "*"
+coreapi = "*"
+"django-rest-swagger" = "*"
 
 [dev-packages]
 
 pytest = "*"
 "flake8" = "*"
 "pytest-flake8" = "*"
 coverage = "*"
-coreapi = "*"
 coveralls = "*"

Pipfile.lock

@@ -102,15 +102,15 @@ Create them using the admin console, which you will be able to access locally at
 
 ## API
 We run <a href=http://www.django-rest-framework.org>DRF</a>, which exposes a browesable API:
-<a href="https://www.vol.community/api/">www.vol.community/api</a>.
+<a href="https://www.vol.community/api/">www.vol.community/api</a>. Alternatively use Swagger/OpenAPI at <a href="https://www.vol.community/api/swagger">www.vol.community/api/swagger</a>
 
 Read only access can be accessed without tokens, mutating requires using basic auth or having
 an API token.
 
 Pass tokens by adding an Authorization header like so:
 
 ```shell
-curl -X DELETE https://www.vol.community/api/v0.0.1/jobs/1 --header "Content-Type: application/json" -H 'Authorization: Token 9b13d4942b24dc0eb12eb77f3eaf37f23b250175'
+curl -X DELETE https://www.vol.community/api/jobs/1 --header "Content-Type: application/json" -H 'Authorization: Token 9b13d4942b24dc0eb12eb77f3eaf37f23b250175'
 ```
 
 If you are looking for a client, <a href=https://github.com/core-api>core-api</a> clients do
@@ -122,13 +122,13 @@ If you are looking for a client, <a href=https://github.com/core-api>core-api</a
  In [3]: client.get('localhost:8000/api')
  In [4]: client.get('http://localhost:8000/api')
  Out[4]:
- OrderedDict([('labels', 'http://localhost:8000/api/v0.0.1/labels'),
+ OrderedDict([('labels', 'http://localhost:8000/api/labels'),
               ('organisations',
-               'http://localhost:8000/api/v0.0.1/organisations'),
-              ('sites', 'http://localhost:8000/api/v0.0.1/sites'),
-              ('jobs', 'http://localhost:8000/api/v0.0.1/jobs')])
+               'http://localhost:8000/api/organisations'),
+              ('sites', 'http://localhost:8000/api/sites'),
+              ('jobs', 'http://localhost:8000/api/jobs')])
 
- In [5]: client.get('http://localhost:8000/api/v0.0.1/jobs')
+ In [5]: client.get('http://localhost:8000/api/jobs')
  Out[5]:
  OrderedDict([('count', 4),
               ('next', None),

README.md

@@ -16,7 +16,7 @@
 
 class IndexViewTests(APITestCase):
     def setUp(self):
-        self.base_url = "/api/%s" % settings.REST_FRAMEWORK['DEFAULT_VERSION']
+        self.base_url = "/api"
         # TODO: don't be lazy and create roles too, and use a less privileged user
         user = User.objects.create_superuser('admin', '[email protected]', 'test123')
         self.token = Token.objects.create(user=user)
@@ -42,8 +42,13 @@ def test_index_insecure_redirects(self):
         response = self.client.get('/api', secure=False)
         self.assertEqual(response.status_code, 301)
 
+    # Assert that we will be redirect to "/api" if we hit "/api"
     def test_index_view(self):
         response = self.client.get('/api', secure=True)
+        self.assertEqual(response.status_code, 302)
+
+    def test_index_view_trailing(self):
+        response = self.client.get('/api/', secure=True)
         self.assertEqual(response.status_code, 200)
         self.assertContains(response, "labels")
 

api/test_views.py

@@ -1,8 +1,16 @@
 from django.conf.urls import url, include
+from django.views.generic.base import RedirectView
+
 from rest_framework import routers
+from rest_framework.schemas import get_schema_view
+from rest_framework_swagger.renderers import OpenAPIRenderer, SwaggerUIRenderer
 
 from . import views
 
+schema_view = get_schema_view(title="Vol.community API",
+                              renderer_classes=[OpenAPIRenderer, SwaggerUIRenderer]
+                              )
+
 router = routers.DefaultRouter(trailing_slash=False)
 router.register(r'labels', views.LabelViewSet)
 router.register(r'organisations', views.OrganisationViewSet)
@@ -12,11 +20,15 @@
 # Wire up our API using automatic URL routing.
 # Additionally, we include login URLs for the browsable API.
 urlpatterns = [
-    # YOLO clients who do not care about versioning:
-    url(r'', include(router.urls)),
+    # Allow clients to explore our API using Swagger
+    url(r'swagger', schema_view),
+
+    # Redirects to /api to make urls generated by django-rest-api and the swagger
+    # plug work as advertised -without the trailing slash urls would look like:
+    # "http://127.0.0.1:8000/apijobs" instead of "http://127.0.0.1:8000/api/jobs"
+    url(r'^$', RedirectView.as_view(url='/api/', permanent=False), name='index'),
 
-    # Explicit version for the more discerning clients:
-    url(r'^/(?P<version>v[0-9+].[0-9]+.[0-9]+)?/', include(router.urls)),
+    url(r'/', include(router.urls)),
 
     url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework'))
 ]

api/urls.py

@@ -51,7 +51,7 @@ class Job(models.Model):
     organisation = models.ForeignKey(Organisation, on_delete=models.CASCADE)  # One org per job
     sites = models.ManyToManyField(Site)  # Possibly more sites per job
     country = models.CharField(max_length=70)  # TODO: move to country table?
-    region = models.CharField(max_length=70)  # TODO: move to region table?
+    region = models.CharField(max_length=70, null=True)  # TODO: move to region table?
     city = models.CharField(max_length=70)  # TODO: move to city table?
     created_at = models.DateTimeField(auto_now_add=True)
     updated_at = models.DateTimeField(auto_now=True)

vol/models.py

@@ -49,7 +49,8 @@
     'django.contrib.staticfiles',
     'analytical',
     'rest_framework',
-    'rest_framework.authtoken'
+    'rest_framework.authtoken',
+    'rest_framework_swagger'
 ]
 
 MIDDLEWARE = [
@@ -168,7 +169,7 @@
     'DEFAULT_PERMISSION_CLASSES': [
         'rest_framework.permissions.DjangoModelPermissionsOrAnonReadOnly'
     ],
-    'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.URLPathVersioning',
+    'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.AcceptHeaderVersioning',
     # What we'll use if no version is specified
     'DEFAULT_VERSION': 'v0.0.1',
     # Other versions will receive a 404 with body "Invalid version in URL path."