💡 Add swagger docs for the API

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

Author: sbs2001

requirements.txt

@@ -12,6 +12,7 @@ dj-database-url==0.4.2
 Django==3.0.7
 django-filter==2.2.0
 djangorestframework==3.11.0
+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,17 +46,17 @@ class Vulnerability(models.Model):
 
     @property
     def vulnerable_to(self):
-        qs = PackageRelatedVulnerability.objects.filter(
-            vulnerability_id=self.id, is_vulnerable=True
-        ).select_related("package")
-        return [rel.package for rel in qs]
+        return self.package_set.filter(
+            packagerelatedvulnerability__is_vulnerable=True,
+            packagerelatedvulnerability__vulnerability_id=self.id,
+        )
 
     @property
     def resolved_to(self):
-        qs = PackageRelatedVulnerability.objects.filter(
-            vulnerability_id=self.id, is_vulnerable=False
-        ).select_related("package")
-        return [rel.package for rel in qs]
+        return self.package_set.filter(
+            packagerelatedvulnerability__is_vulnerable=False,
+            packagerelatedvulnerability__vulnerability_id=self.id,
+        )
 
     def __str__(self):
         return self.cve_id or self.summary
@@ -96,17 +96,17 @@ class Package(PackageURLMixin):
 
     @property
     def vulnerable_to(self):
-        qs = PackageRelatedVulnerability.objects.filter(
-            package_id=self.id, is_vulnerable=True
-        ).select_related("vulnerability")
-        return [rel.vulnerability for rel in qs]
+        return self.vulnerabilities.filter(
+            packagerelatedvulnerability__is_vulnerable=True,
+            packagerelatedvulnerability__package_id=self.id,
+        )
 
     @property
     def resolved_to(self):
-        qs = PackageRelatedVulnerability.objects.filter(
-            package_id=self.id, is_vulnerable=False
-        ).select_related("vulnerability")
-        return [rel.vulnerability for rel in qs]
+        return self.vulnerabilities.filter(
+            packagerelatedvulnerability__is_vulnerable=False,
+            packagerelatedvulnerability__package_id=self.id,
+        )
 
     class Meta:
         unique_together = ("name", "namespace", "type", "version", "qualifiers", "subpath")

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,6 +47,7 @@
     'vulnerabilities',
     'rest_framework',
     'django_filters',
+    'drf_yasg',
 ]
 
 MIDDLEWARE = [

vulnerablecode/urls.py

@@ -22,15 +22,25 @@
 #  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
 
+schema_view = get_schema_view(
+   openapi.Info(
+      title="VulnerableCode API",
+      default_version="v1"
+   ),
+   public=True,
+   permission_classes=(permissions.AllowAny,),
+)
 
-api_router = DefaultRouter(trailing_slash=False)
+api_router = DefaultRouter()
 api_router.register(r"packages", PackageViewSet)
 # `DefaultRouter` requires `basename` when registering viewsets which don't
 # define a queryset.
@@ -39,5 +49,6 @@
 
 urlpatterns = [
     path("admin/", admin.site.urls),
-    re_path(r"^api/", include(api_router.urls)),
+    path(r"api/", include(api_router.urls)),
+    path(r'swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
 ]