Add swagger API documentation when DRF is enabled (#3536)

* Adds swagger api documentation when drf is enabled

Changes
* Integrate drf-spectacular module
* Added routes and tests for swagger-ui

* Removes swagger ui tests when drf is not enabled

* Changes url names and documentation title

* Apply suggestions from code review

Co-authored-by: Fábio C. Barrionuevo da Luz <bnafta@gmail.com>
Co-authored-by: Bruno Alla <browniebroke@users.noreply.github.com>

* Fixes typos and linting issues

* Update domain in swagger description

Co-authored-by: Fábio C. Barrionuevo da Luz <bnafta@gmail.com>

Co-authored-by: Fábio C. Barrionuevo da Luz <bnafta@gmail.com>
Co-authored-by: Bruno Alla <browniebroke@users.noreply.github.com>

hooks/post_gen_project.py

@@ -327,6 +327,11 @@ def remove_drf_starter_files():
             "{{cookiecutter.project_slug}}", "users", "tests", "test_drf_views.py"
         )
     )
+    os.remove(
+        os.path.join(
+            "{{cookiecutter.project_slug}}", "users", "tests", "test_swagger_ui.py"
+        )
+    )
 
 
 def remove_storages_module():

{{cookiecutter.project_slug}}/config/settings/base.py

@@ -84,6 +84,7 @@ THIRD_PARTY_APPS = [
     "rest_framework",
     "rest_framework.authtoken",
     "corsheaders",
+    "drf_spectacular",
 {%- endif %}
 ]
 
@@ -334,6 +335,18 @@ REST_FRAMEWORK = {
 # django-cors-headers - https://github.com/adamchainz/django-cors-headers#setup
 CORS_URLS_REGEX = r"^/api/.*$"
 
+# By Default swagger ui is available only to admin user. You can change permission classs to change that
+# See more configuration options at https://drf-spectacular.readthedocs.io/en/latest/settings.html#settings
+SPECTACULAR_SETTINGS = {
+    "TITLE": "{{ cookiecutter.project_name }} API",
+    "DESCRIPTION": "Documentation of API endpoiints of {{ cookiecutter.project_name }}",
+    "VERSION": "1.0.0",
+    "SERVE_PERMISSIONS": ["rest_framework.permissions.IsAdminUser"],
+    "SERVERS": [
+        {"url": "https://127.0.0.1:8000", "description": "Local Development server"},
+        {"url": "https://{{ cookiecutter.domain_name }}", "description": "Production server"},
+    ],
+}
 {%- endif %}
 # Your stuff...
 # ------------------------------------------------------------------------------

{{cookiecutter.project_slug}}/config/urls.py

@@ -8,6 +8,7 @@ from django.urls import include, path
 from django.views import defaults as default_views
 from django.views.generic import TemplateView
 {%- if cookiecutter.use_drf == 'y' %}
+from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView
 from rest_framework.authtoken.views import obtain_auth_token
 {%- endif %}
 
@@ -35,6 +36,12 @@ urlpatterns += [
     path("api/", include("config.api_router")),
     # DRF auth token
     path("auth-token/", obtain_auth_token),
+    path("api/schema/", SpectacularAPIView.as_view(), name="api-schema"),
+    path(
+        "api/docs/",
+        SpectacularSwaggerView.as_view(url_name="api-schema"),
+        name="api-docs",
+    ),
 ]
 {%- endif %}
 

{{cookiecutter.project_slug}}/requirements/base.txt

@@ -43,4 +43,6 @@ django-redis==5.2.0  # https://github.com/jazzband/django-redis
 # Django REST Framework
 djangorestframework==3.13.1  # https://github.com/encode/django-rest-framework
 django-cors-headers==3.11.0 # https://github.com/adamchainz/django-cors-headers
+# DRF-spectacular for api documentation
+drf-spectacular==0.21.1
 {%- endif %}

{{cookiecutter.project_slug}}/{{cookiecutter.project_slug}}/users/tests/test_swagger_ui.py

@@ -0,0 +1,16 @@
+import pytest
+from django.urls import reverse
+
+pytestmark = pytest.mark.django_db
+
+
+def test_swagger_accessible_by_admin(admin_client):
+    url = reverse("api-docs")
+    response = admin_client.get(url)
+    assert response.status_code == 200
+
+
+def test_swagger_ui_not_accessible_by_normal_user(client):
+    url = reverse("api-docs")
+    response = client.get(url)
+    assert response.status_code == 403