Replace deprecated coreapi with drf-yasg for API documentation (#314)

Signed-off-by: tdruez <tdruez@nexb.com>

Author: tdruez

Makefile

@@ -136,7 +136,7 @@ postgresdb_clean:
 	@${SUDO_POSTGRES} dropuser '${DB_USERNAME}' || true
 
 run:
-	${MANAGE} runserver 8000 --insecure
+	DJANGO_RUNSERVER_HIDE_WARNING=true ${MANAGE} runserver 8000 --insecure
 
 worker:
 	${MANAGE} rqworker

component_catalog/api.py

@@ -11,16 +11,13 @@
 from django.db import transaction
 from django.forms.widgets import HiddenInput
 
-import coreapi
-import coreschema
 import django_filters
 from packageurl.contrib import url2purl
 from packageurl.contrib.django.filters import PackageURLFilter
 from rest_framework import serializers
 from rest_framework.decorators import action
 from rest_framework.fields import ListField
 from rest_framework.response import Response
-from rest_framework.schemas import AutoSchema
 
 from component_catalog.admin import ComponentAdmin
 from component_catalog.admin import PackageAdmin
@@ -922,24 +919,7 @@ def about(self, request, uuid):
         package = self.get_object()
         return Response({"about_data": package.as_about_yaml()})
 
-    download_url_description = (
-        "A single, or list of, Download URL(s).<br><br>"
-        '<b>cURL style</b>: <code>-d "download_url=url1&download_url=url2"</code><br><br>'
-        '<b>Python</b>: <code>data = {"download_url": ["url1", "url2"]}</code>'
-    )
-
-    add_action_schema = AutoSchema(
-        manual_fields=[
-            coreapi.Field(
-                "download_url",
-                required=True,
-                location="body",
-                schema=coreschema.String(description=download_url_description),
-            ),
-        ]
-    )
-
-    @action(detail=False, methods=["post"], name="Package Add", schema=add_action_schema)
+    @action(detail=False, methods=["post"], name="Package Add")
     def add(self, request):
         """
         Alternative way to add a package providing only its `download_url`.

dejacode/settings.py

@@ -317,6 +317,7 @@ def gettext_noop(s):
     "django.contrib.admin",
     "rest_framework",
     "rest_framework.authtoken",
+    "drf_yasg",
     "django_rq",
     "crispy_forms",
     "crispy_bootstrap5",
@@ -625,7 +626,6 @@ def get_fake_redis_connection(config, use_strict_redis):
         "user": REST_API_RATE_THROTTLE,
     },
     "DEFAULT_PAGINATION_CLASS": "dje.api_custom.PageSizePagination",
-    "DEFAULT_SCHEMA_CLASS": "rest_framework.schemas.coreapi.AutoSchema",
     "VIEW_NAME_FUNCTION": "dje.api_custom.get_view_name",
     "URL_FIELD_NAME": "api_url",  # Default 'url' used as a field on the Package model
 }

dejacode/urls.py

@@ -11,14 +11,12 @@
 from django.contrib import admin
 from django.contrib.auth import views as auth_views
 from django.contrib.auth.decorators import login_required
-from django.template.loader import render_to_string
 from django.urls import path
 from django.views.defaults import page_not_found
 from django.views.generic import RedirectView
 from django.views.generic import TemplateView
 
 from notifications.views import mark_all_as_read
-from rest_framework.documentation import include_docs_urls
 from rest_framework.routers import DefaultRouter
 
 from component_catalog.api import ComponentViewSet
@@ -39,6 +37,7 @@
 from dje.views import GlobalSearchListView
 from dje.views import IntegrationsStatusView
 from dje.views import UnreadNotificationsList
+from dje.views import api_docs_view
 from dje.views import home_view
 from dje.views import index_dispatch
 from dje.views import urn_resolve_view
@@ -161,28 +160,16 @@
 
 urlpatterns += [
     path("notifications/", include((notification_patterns, "notifications"))),
-]
-
-urlpatterns += [
     path("purldb/", include(("purldb.urls", "purldb"))),
 ]
 
-api_docs_urls = include_docs_urls(
-    title="DejaCode REST API",
-    public=False,
-    description=render_to_string(
-        "rest_framework/docs/description.html",
-        context={"site_url": settings.SITE_URL.rstrip("/")},
-    ),
-)
-
-# Force login_required on all API documentation URLs.
-for doc_url in api_docs_urls[0]:
-    doc_url.callback = login_required(doc_url.callback)
+api_docs_patterns = [
+    path("", login_required(api_docs_view.with_ui("redoc")), name="docs-index"),
+]
 
 urlpatterns += [
     path("api/v2/", include((api_router.urls, "api_v2"))),
-    path("api/v2/docs/", api_docs_urls),
+    path("api/v2/docs/", include((api_docs_patterns, "api-docs"))),
 ]
 
 if settings.ENABLE_SELF_REGISTRATION:

dje/templates/admin/docs/index.html

@@ -19,7 +19,6 @@
 
         {% if code_style %}<style>{{ code_style }}</style>{% endif %}
         <script src="{% static 'rest_framework/js/coreapi-0.1.1.js' %}"></script>
-        <script src="{% url 'api-docs:schema-js' %}"></script>
 
         <script src="{% static 'rest_framework/js/jquery-3.7.1.min.js' %}"></script>
         <script src="{% static 'rest_framework/js/bootstrap.min.js' %}"></script>

dje/templates/rest_framework/docs/index.html

@@ -65,6 +65,16 @@ def test_admin_history_view_content(self):
         self.assertContains(response, "<td>Added.</td>")
         self.assertContains(response, "<td>Changed name.</td>")
 
+    def test_admin_docs_models_view(self):
+        url_docs_models = reverse("admin:docs_models")
+        response = self.client.get(url_docs_models)
+        self.assertEqual(302, response.status_code)
+        self.assertRedirects(response, f"/login/?next={url_docs_models}")
+
+        self.client.login(username=self.super_user.username, password="secret")
+        response = self.client.get(url_docs_models)
+        self.assertContains(response, "Models documentation")
+
     def test_dataspaced_admin_advanced_search_method(self):
         search_fields = ["f1", "f2"]
 

dje/tests/test_admin.py

@@ -49,6 +49,7 @@
 from django.shortcuts import redirect
 from django.shortcuts import render
 from django.template.defaultfilters import pluralize
+from django.template.loader import render_to_string
 from django.test import RequestFactory
 from django.urls import NoReverseMatch
 from django.urls import reverse
@@ -70,6 +71,8 @@
 
 import django_otp
 from django_filters.views import FilterView
+from drf_yasg import openapi
+from drf_yasg.views import get_schema_view
 from grappelli.views.related import AutocompleteLookup
 from grappelli.views.related import RelatedLookup
 from notifications import views as notifications_views
@@ -2429,3 +2432,16 @@ def get(self, request, *args, **kwargs):
             filename=filename,
             content_type="application/json",
         )
+
+
+api_docs_view = get_schema_view(
+    openapi.Info(
+        title="DejaCode REST API",
+        default_version="v2",
+        description=render_to_string(
+            "rest_framework/docs/description.html",
+            context={"site_url": settings.SITE_URL.rstrip("/")},
+        ),
+    ),
+    public=False,
+)

dje/views.py

@@ -70,13 +70,11 @@ install_requires =
     django_altcha==0.1.3
     # REST API
     djangorestframework==3.16.0
-    # API documentation, `coreapi` and its requirements:
-    coreapi==2.3.3
-    MarkupSafe==3.0.2
-    coreschema==0.0.4
-    itypes==1.2.0
-    Jinja2==3.1.6
+    # API documentation
+    drf-yasg==1.21.10
     uritemplate==4.1.1
+    inflection==0.5.1
+    pytz==2025.2
     # Track failed login attempts
     django-axes==8.0.0
     # Multi-factor authentication
@@ -150,6 +148,8 @@ install_requires =
     # AboutCode Toolkit
     aboutcode_toolkit==11.1.1
     click==8.2.1
+    Jinja2==3.1.6
+    MarkupSafe==3.0.2
     saneyaml==0.6.1
     openpyxl==3.1.5
     et-xmlfile==2.0.0