TG-162 Add API documentation

Author: niccolomineo

bootstrap/collector.py

@@ -39,6 +39,7 @@ def collect(
 ):
     """Collect options and run the setup."""
     project_slug = clean_project_slug(project_name, project_slug)
+    project_description = clean_project_description()
     service_slug = clean_service_slug(service_slug)
     project_dirname = clean_project_dirname(project_dirname, project_slug, service_slug)
     project_url_dev = validate_or_prompt_url(
@@ -72,6 +73,7 @@ def collect(
         "output_dir": output_dir,
         "project_name": project_name,
         "project_slug": project_slug,
+        "project_description": project_description,
         "project_dirname": project_dirname,
         "service_dir": service_dir,
         "service_slug": service_slug,
@@ -119,6 +121,11 @@ def clean_project_slug(project_name, project_slug):
     )
 
 
+def clean_project_description(project_slug):
+    """Return the project description."""
+    return click.prompt("Project description", default="")
+
+
 def clean_service_slug(service_slug):
     """Return the service slug."""
     return slugify(

bootstrap/runner.py

@@ -26,6 +26,7 @@ def run(
     output_dir,
     project_name,
     project_slug,
+    project_description,
     project_dirname,
     service_dir,
     service_slug,
@@ -51,6 +52,7 @@ def run(
         output_dir,
         project_name,
         project_slug,
+        project_description,
         project_dirname,
         service_slug,
         internal_service_port,
@@ -91,6 +93,7 @@ def init_service(
     output_dir,
     project_name,
     project_slug,
+    project_description,
     project_dirname,
     service_slug,
     internal_service_port,
@@ -110,6 +113,7 @@ def init_service(
             "project_dirname": project_dirname,
             "project_name": project_name,
             "project_slug": project_slug,
+            "project_description": project_description,
             "project_url_dev": project_url_dev,
             "project_url_prod": project_url_prod,
             "project_url_stage": project_url_stage,

setup.py

@@ -20,6 +20,7 @@
 @click.option("--output-dir", default=OUTPUT_DIR)
 @click.option("--project-name", prompt=True)
 @click.option("--project-slug", callback=slugify_option)
+@click.option("--project-description")
 @click.option("--project-dirname")
 @click.option("--service-slug", callback=slugify_option)
 @click.option("--internal-service-port", default=8000, type=int)

{{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.SessionAuthentication",
+        ],
+        "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",
+            ),
+        ),
+    )
+]