💡 Add swagger docs for the API

Signed-off-by: Shivam Sandbhor <shivam.sandbhor@gmail.com>

Author: sbs2001

requirements.txt

@@ -13,6 +13,7 @@ Django==3.0.7
 django-filter==2.2.0
 djangorestframework==3.11.0
 django-widget-tweaks==1.4.8
+drf-yasg==1.17.1
 gunicorn==19.7.1
 importlib-metadata==1.3.0
 ipython==7.13.0

vulnerabilities/api.py

@@ -60,7 +60,7 @@ class Meta:
         fields = ["url", "vulnerability_id"]
 
 
-class VulnerabilitySerializer(serializers.ModelSerializer):
+class VulnerabilitySerializer(serializers.HyperlinkedModelSerializer):
     references = VulnerabilityReferenceSerializer(many=True, source="vulnerabilityreference_set")
     resolved_packages = HyperLinkedPackageSerializer(
         many=True, source="resolved_to", read_only=True
@@ -74,7 +74,7 @@ class Meta:
         fields = "__all__"
 
 
-class PackageSerializer(serializers.ModelSerializer):
+class PackageSerializer(serializers.HyperlinkedModelSerializer):
     unresolved_vulnerabilities = HyperLinkedVulnerabilitySerializer(
         many=True, source="vulnerable_to", read_only=True
     )
@@ -86,6 +86,7 @@ class PackageSerializer(serializers.ModelSerializer):
     class Meta:
         model = Package
         fields = [
+            "url",
             "type",
             "namespace",
             "name",

vulnerabilities/models.py

@@ -46,11 +46,15 @@ class Vulnerability(models.Model):
 
     @property
     def vulnerable_to(self):
-        return self.packagerelatedvulnerability_set.filter(is_vulnerable=True)
+        return self.package_set.filter(
+            packagerelatedvulnerability__is_vulnerable=True,
+        )
 
     @property
     def resolved_to(self):
-        return self.packagerelatedvulnerability_set.filter(is_vulnerable=False)
+        return self.package_set.filter(
+            packagerelatedvulnerability__is_vulnerable=False,
+        )
 
     def __str__(self):
         return self.cve_id or self.summary
@@ -90,11 +94,15 @@ class Package(PackageURLMixin):
 
     @property
     def vulnerable_to(self):
-        return self.packagerelatedvulnerability_set.filter(is_vulnerable=True)
+        return self.vulnerabilities.filter(
+            packagerelatedvulnerability__is_vulnerable=True,
+        )
 
     @property
     def resolved_to(self):
-        return self.packagerelatedvulnerability_set.filter(is_vulnerable=False)
+        return self.vulnerabilities.filter(
+            packagerelatedvulnerability__is_vulnerable=False,
+        )
 
     class Meta:
         unique_together = ("name", "namespace", "type", "version", "qualifiers", "subpath")

vulnerabilities/templates/vulnerability.html

@@ -63,9 +63,9 @@ <h3> Patched Packages </h3>
                 <tr>
                     <th> Package URL </th>
                 </tr>
-                {% for ref in vulnerability.resolved_to.all %}
+                {% for package in vulnerability.resolved_to.all %}
                 <tr>
-                    <td><a href ="{% url 'package_view' ref.package.pk %}"> {{ref.package}} </a> </td>
+                    <td><a href ="{% url 'package_view' package.pk %}"> {{package.package_url}} </a> </td>
                 </tr>
                 {% endfor %}
             </table>
@@ -79,9 +79,9 @@ <h3> Vulnerable Packages </h3>
                 <tr>
                     <th> Package URL </th>
                 </tr>
-                {% for ref in vulnerability.vulnerable_to.all %}
+                {% for package in vulnerability.vulnerable_to.all %}
                 <tr>
-                    <td><a href ="{% url 'package_view' ref.package.pk %}"> {{ref.package}}</a></td>
+                    <td><a href ="{% url 'package_view' package.pk %}"> {{package.package_url}}</a></td>
                 </tr>
                 {% endfor %}
             </table>

vulnerabilities/tests/test_api.py

@@ -57,25 +57,25 @@ def test_query_qualifier_filtering(self):
 
         # check filtering when qualifiers are not normalized
         test_purl = quote("pkg:deb/vlc@1.50-1.1?foo=bar&tar=ball")
-        response = self.client.get(f"/api/packages?purl={test_purl}", format="json").data
+        response = self.client.get(f"/api/packages/?purl={test_purl}", format="json").data
 
         self.assertEqual(1, response["count"])
         self.assertEqual(pk_multi_qf.qualifiers, response["results"][0]["qualifiers"])
 
         test_purl = quote("pkg:deb/vlc@1.50-1.1?tar=ball&foo=bar")
-        response = self.client.get(f"/api/packages?purl={test_purl}", format="json").data
+        response = self.client.get(f"/api/packages/?purl={test_purl}", format="json").data
 
         self.assertEqual(1, response["count"])
         self.assertEqual(pk_multi_qf.qualifiers, response["results"][0]["qualifiers"])
 
         # check filtering when there is intersection of qualifiers between packages
         test_purl = quote("pkg:deb/vlc@1.50-1.1?foo=bar")
-        response = self.client.get(f"/api/packages?purl={test_purl}", format="json").data
+        response = self.client.get(f"/api/packages/?purl={test_purl}", format="json").data
 
         self.assertEqual(1, response["count"])
 
     def test_query_by_name(self):
-        response = self.client.get("/api/packages?name=mimetex", format="json").data
+        response = self.client.get("/api/packages/?name=mimetex", format="json").data
 
         self.assertEqual(3, response["count"])
 
@@ -91,7 +91,7 @@ def test_query_by_name(self):
         self.assertIn("pkg:deb/debian/mimetex@1.74-1?distro=jessie", purls)
 
     def test_query_by_invalid_package_url(self):
-        url = "/api/packages?purl=invalid_purl"
+        url = "/api/packages/?purl=invalid_purl"
         response = self.client.get(url, format="json")
 
         self.assertEqual(400, response.status_code)
@@ -100,7 +100,7 @@ def test_query_by_invalid_package_url(self):
         self.assertIn("invalid_purl", error)
 
     def test_query_by_package_url(self):
-        url = "/api/packages?purl=pkg:deb/debian/mimetex@1.50-1.1?distro=jessie"
+        url = "/api/packages/?purl=pkg:deb/debian/mimetex@1.50-1.1?distro=jessie"
         response = self.client.get(url, format="json").data
 
         self.assertEqual(1, response["count"])
@@ -113,7 +113,7 @@ def test_query_by_package_url(self):
         self.assertNotIn("1.74-1", versions)
 
     def test_query_by_package_url_without_namespace(self):
-        url = "/api/packages?purl=pkg:deb/mimetex@1.50-1.1"
+        url = "/api/packages/?purl=pkg:deb/mimetex@1.50-1.1"
         response = self.client.get(url, format="json").data
 
         self.assertEqual(2, response["count"])
@@ -130,7 +130,7 @@ class TestUbuntuResponse(TestCase):
     fixtures = ["ubuntu.json"]
 
     def test_ubuntu_response(self):
-        response = self.client.get("/api/packages?name=automake", format="json")
+        response = self.client.get("/api/packages/?name=automake", format="json")
 
         result = response.data.get("results")[0]
         self.assertEqual("automake", result["name"])
@@ -144,7 +144,7 @@ def test_vulnerability_package_relations(self):
         test_pkgs = choices(Package.objects.all(), k=5)
         for test_pkg in test_pkgs:
 
-            pkg_response = self.client.get(f"/api/packages/{test_pkg.id}", format="json").data
+            pkg_response = self.client.get(f"/api/packages/{test_pkg.id}/", format="json").data
             resolved_vulns = {
                 vuln["vulnerability_id"] for vuln in pkg_response["resolved_vulnerabilities"]
             }
@@ -154,7 +154,7 @@ def test_vulnerability_package_relations(self):
 
             for vuln in resolved_vulns:
                 vuln_resp = self.client.get(
-                    f"/api/vulnerabilities?vulnerability_id={vuln}", format="json"
+                    f"/api/vulnerabilities/?vulnerability_id={vuln}", format="json"
                 ).data
                 resolved_purls = {
                     package["purl"] for package in vuln_resp["results"][0]["resolved_packages"]
@@ -163,7 +163,7 @@ def test_vulnerability_package_relations(self):
 
             for vuln in unresolved_vulns:
                 vuln_resp = self.client.get(
-                    f"/api/vulnerabilities?vulnerability_id={vuln}", format="json"
+                    f"/api/vulnerabilities/?vulnerability_id={vuln}", format="json"
                 ).data
                 unresolved_purls = {
                     package["purl"] for package in vuln_resp["results"][0]["unresolved_packages"]

vulnerablecode/settings.py

@@ -47,7 +47,8 @@
     'vulnerabilities',
     'rest_framework',
     'django_filters',
-    'widget_tweaks'
+    'widget_tweaks',
+    'drf_yasg',
 ]
 
 MIDDLEWARE = [

vulnerablecode/urls.py

@@ -22,11 +22,14 @@
 #  Visit https://github.com/nexB/vulnerablecode/ for support and download.
 
 from django.contrib import admin
-from django.urls import include, path, re_path
-
+from django.urls import include, path
+from rest_framework import permissions
+from drf_yasg.views import get_schema_view
+from drf_yasg import openapi
 from rest_framework.routers import DefaultRouter
 
 from vulnerabilities.api import PackageViewSet
+from vulnerabilities.api import VulnerabilityViewSet
 from vulnerabilities.views import HomePage
 from vulnerabilities.views import PackageSearchView
 from vulnerabilities.views import PackageUpdate
@@ -38,22 +41,21 @@
 from vulnerabilities.views import VulnerabilityCreate
 from vulnerabilities.views import VulnerabilityReferenceCreate
 
+schema_view = get_schema_view(
+    openapi.Info(title="VulnerableCode API", default_version="v1"),
+    public=True,
+    permission_classes=(permissions.AllowAny,),
+)
 
 api_router = DefaultRouter()
 api_router.register(r"packages", PackageViewSet)
-from vulnerabilities.api import VulnerabilityView
-
-
-api_router = DefaultRouter)
-api_router.register(r"packages", PackageViewSet)
 # `DefaultRouter` requires `basename` when registering viewsets which don't
 # define a queryset.
 api_router.register(r"vulnerabilities", VulnerabilityViewSet, basename="vulnerability")
 
 
 urlpatterns = [
     path("admin/", admin.site.urls),
-    path("api/", include(api_router.urls)),
     path("packages/search", PackageSearchView.as_view(), name="package_search"),
     path("packages/<int:pk>", PackageUpdate.as_view(), name="package_view"),
     path("vulnerabilities/<int:pk>", VulnerabilityDetails.as_view(), name="vulnerability_view"),
@@ -86,4 +88,6 @@
         name="vulnerability_reference_create",
     ),
     path("", HomePage.as_view(), name="home"),
+    path(r"api/", include(api_router.urls)),
+    path(r"api/docs", schema_view.with_ui("swagger", cache_timeout=0), name="schema-swagger-ui"),
 ]