TG-162 Add API Documentation

Author: niccolomineo

{{cookiecutter.project_dirname}}/.env_template

@@ -15,4 +15,5 @@ [email protected]
 DJANGO_SUPERUSER_PASSWORD={{ cookiecutter.project_slug }}
 DJANGO_SUPERUSER_USERNAME=${USER}
 EMAIL_URL=console:///
+DJANGO_ENABLE_API_DOCS=True
 PYTHONBREAKPOINT=ipdb.set_trace

{{cookiecutter.project_dirname}}/docker-compose.yaml

@@ -26,6 +26,7 @@ services:
       - DJANGO_SUPERUSER_PASSWORD
       - DJANGO_SUPERUSER_USERNAME
       - EMAIL_URL
+      - ENABLE_API_DOCS
       - PYTHONBREAKPOINT
       - SERVICE_PORT
     ports:

{{cookiecutter.project_dirname}}/requirements/common.in

@@ -1,2 +1,5 @@
 # pip-compile --output-file common.txt common.in
 -r base.in
+djangorestframework-camel-case~=1.3.0
+djangorestframework~=3.13.0
+drf-spectacular~=0.22.0

{{cookiecutter.project_dirname}}/terraform/main.tf

@@ -91,6 +91,7 @@ resource "kubernetes_secret_v1" "env" {
     {
       DJANGO_SECRET_KEY = random_password.django_secret_key.result
       EMAIL_URL         = var.email_url
+      ENABLE_API_DOCS   = var.environment_slug == "prod" ? "False" : "True"
       SENTRY_DSN        = var.sentry_dsn
     },
     local.use_s3 ? {

{{cookiecutter.project_dirname}}/{{cookiecutter.django_settings_dirname}}/settings.py

@@ -47,6 +47,7 @@ class ProjectDefault(Configuration):
         "django.contrib.sessions",
         "django.contrib.messages",
         "django.contrib.staticfiles",
+        "drf_spectacular",
     ]
 
     MIDDLEWARE = [
@@ -181,6 +182,51 @@ class ProjectDefault(Configuration):
 
     SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")
 
+    # API Documentation
+
+    ENABLE_API_DOCS = values.BooleanValue(False)
+
+    # Django REST Framework
+    # https://www.django-rest-framework.org/api-guide/settings/
+
+    REST_FRAMEWORK: dict = {
+        "DEFAULT_AUTHENTICATION_CLASSES": [
+            "rest_framework.authentication.TokenAuthentication"
+        ],
+        "DEFAULT_FILTER_BACKENDS": [
+            "django_filters.rest_framework.DjangoFilterBackend"
+        ],
+        "DEFAULT_PARSER_CLASSES": [
+            "djangorestframework_camel_case.parser.CamelCaseMultiPartParser",
+            "djangorestframework_camel_case.parser.CamelCaseJSONParser",
+        ],
+        "DEFAULT_PERMISSION_CLASSES": ["rest_framework.permissions.IsAuthenticated"],
+        "DEFAULT_RENDERER_CLASSES": [
+            "djangorestframework_camel_case.render.CamelCaseJSONRenderer",
+        ],
+        "DEFAULT_SCHEMA_CLASS": "drf_spectacular.openapi.AutoSchema",
+    }
+
+    # drf-spectacular
+    # https://drf-spectacular.readthedocs.io/en/latest/
+
+    SPECTACULAR_SETTINGS = {
+        "TITLE": "{{ cookiecutter.project_name }} - API documentation",
+        "DESCRIPTION": "{{ cookiecutter.project_description }}",
+        "VERSION": "1.0.0",
+        "CAMELIZE_NAMES": True,
+        "SWAGGER_UI_SETTINGS": {
+            "deepLinking": True,
+            "displayRequestDuration": True,
+            "persistAuthorization": True,
+            "syntaxHighlight.activate": True,
+        },
+        "POSTPROCESSING_HOOKS": [
+            "drf_spectacular.hooks.postprocess_schema_enums",
+            "drf_spectacular.contrib.djangorestframework_camel_case.camelize_serializer_fields",  # noqa
+        ],
+    }
+
 
 class Local(ProjectDefault):
     """The local settings."""
@@ -251,6 +297,18 @@ class Local(ProjectDefault):
             "verbose_names": True,
         }
 
+    # Django REST Framework
+    # https://www.django-rest-framework.org/api-guide/settings/
+
+    REST_FRAMEWORK = {
+        **ProjectDefault.REST_FRAMEWORK,
+        "DEFAULT_RENDERER_CLASSES": [
+            *ProjectDefault.REST_FRAMEWORK["DEFAULT_RENDERER_CLASSES"],
+            "djangorestframework_camel_case.render.CamelCaseBrowsableAPIRenderer",
+        ],
+    }
+
+
 
 class Testing(ProjectDefault):
     """The testing settings."""

{{cookiecutter.project_dirname}}/{{cookiecutter.django_settings_dirname}}/urls.py

@@ -23,6 +23,21 @@
 
 urlpatterns = [
     path("admin/", admin.site.urls),
+    path(
+        "api/",
+        include(
+            (
+                [
+                    *(
+                        [path("", include("{{ cookiecutter.project_slug }}.urls_apibrowser"))]
+                        if settings.ENABLE_API_DOCS
+                        else []
+                    ),
+                ],
+                "api",
+            )
+        ),
+    ),
 ]
 
 if settings.DEBUG:  # pragma: no cover

{{cookiecutter.project_dirname}}/{{cookiecutter.django_settings_dirname}}/urls_apibrowser.py

@@ -0,0 +1,29 @@
+"""API browser URL configuration."""
+
+from django.urls import include, path
+from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView
+
+urlpatterns = [
+    path(
+        "browser/",
+        include(
+            (
+                [
+                    path(
+                        "schema/",
+                        SpectacularAPIView.as_view(
+                            urlconf="{{ cookiecutter.project_slug }}.urls"
+                        ),
+                        name="schema",
+                    ),
+                    path(
+                        "docs/",
+                        SpectacularSwaggerView.as_view(url_name="api:browser:schema"),
+                        name="docs",
+                    ),
+                ],
+                "browser",
+            ),
+        ),
+    )
+]