From 721b86723c09a7c8d99a61af949631a237038f26 Mon Sep 17 00:00:00 2001 From: Vikas Yadav Date: Wed, 19 Jan 2022 23:44:36 +0530 Subject: [PATCH] Add swagger API documentation when DRF is enabled (#3536) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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 Co-authored-by: Bruno Alla * Fixes typos and linting issues * Update domain in swagger description Co-authored-by: Fábio C. Barrionuevo da Luz Co-authored-by: Fábio C. Barrionuevo da Luz Co-authored-by: Bruno Alla --- hooks/post_gen_project.py | 5 +++++ .../config/settings/base.py | 13 +++++++++++++ {{cookiecutter.project_slug}}/config/urls.py | 7 +++++++ .../requirements/base.txt | 2 ++ .../users/tests/test_swagger_ui.py | 16 ++++++++++++++++ 5 files changed, 43 insertions(+) create mode 100644 {{cookiecutter.project_slug}}/{{cookiecutter.project_slug}}/users/tests/test_swagger_ui.py diff --git a/hooks/post_gen_project.py b/hooks/post_gen_project.py index 50fcbea2..b2dbb342 100644 --- a/hooks/post_gen_project.py +++ b/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(): diff --git a/{{cookiecutter.project_slug}}/config/settings/base.py b/{{cookiecutter.project_slug}}/config/settings/base.py index 5177c92f..1598373d 100644 --- a/{{cookiecutter.project_slug}}/config/settings/base.py +++ b/{{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... # ------------------------------------------------------------------------------ diff --git a/{{cookiecutter.project_slug}}/config/urls.py b/{{cookiecutter.project_slug}}/config/urls.py index 168d77a8..ab42cc10 100644 --- a/{{cookiecutter.project_slug}}/config/urls.py +++ b/{{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 %} diff --git a/{{cookiecutter.project_slug}}/requirements/base.txt b/{{cookiecutter.project_slug}}/requirements/base.txt index e371135c..d9dbb83e 100644 --- a/{{cookiecutter.project_slug}}/requirements/base.txt +++ b/{{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 %} diff --git a/{{cookiecutter.project_slug}}/{{cookiecutter.project_slug}}/users/tests/test_swagger_ui.py b/{{cookiecutter.project_slug}}/{{cookiecutter.project_slug}}/users/tests/test_swagger_ui.py new file mode 100644 index 00000000..b0c24d91 --- /dev/null +++ b/{{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