feat(api): add swagger ui for documentation

!17

app/api/serializers/itam/device.py

@@ -27,7 +27,6 @@ class DeviceSerializer(serializers.ModelSerializer):
         read_only_fields = [
             'inventorydate',
             'is_global',
-            'organization',
             'slug',
         ]
 

app/api/urls.py

@@ -1,4 +1,5 @@
 from django.urls import path
+
 from rest_framework.routers import DefaultRouter
 from rest_framework.urlpatterns import format_suffix_patterns
 
@@ -21,6 +22,9 @@ router.register('software', software.SoftwareViewSet, basename='software')
 
 
 urlpatterns = [
+    path("config/<slug:slug>/", itam_config.View.as_view(), name="_api_device_config"),
+
+    path("device/inventory/<slug:slug>", inventory.Collect.as_view(), name="_api_device_inventory"),
 
     path("organization/", access.OrganizationList.as_view(), name='_api_orgs'),
     path("organization/<int:pk>/", access.OrganizationDetail.as_view(), name='_api_organization'),
@@ -29,11 +33,6 @@ urlpatterns = [
     path("organization/<int:organization_id>/team/<int:group_ptr_id>/permissions", access.TeamPermissionDetail.as_view(), name='_api_team_permission'),
     path("organization/team/", access.TeamList.as_view(), name='_api_teams'),
 
-
-    path("config/<slug:slug>/", itam_config.View.as_view(), name="_api_device_config"),
-
-    path("device/inventory/<slug:slug>", inventory.Collect.as_view(), name="_api_device_inventory"), 
-
 ]
 
 urlpatterns = format_suffix_patterns(urlpatterns)

app/api/views/itam/device.py

@@ -1,6 +1,8 @@
 from django.db.models import Q
 from django.shortcuts import get_object_or_404
 
+from drf_spectacular.utils import extend_schema
+
 from rest_framework import generics, viewsets
 
 from access.mixin import OrganizationMixin
@@ -23,6 +25,18 @@ class DeviceViewSet(OrganizationMixin, viewsets.ModelViewSet):
     serializer_class = DeviceSerializer
 
 
+    @extend_schema( description='Fetch devices that are from the users assigned organization(s)', methods=["GET"])
+    def list(self, request):
+
+        return super().list(request)
+
+
+    @extend_schema( description='Fetch the selected device', methods=["GET"])
+    def retrieve(self, request, *args, **kwargs):
+
+        return super().retrieve(request, *args, **kwargs)
+
+
     def get_queryset(self):
 
         if self.request.user.is_superuser:
@@ -35,4 +49,7 @@ class DeviceViewSet(OrganizationMixin, viewsets.ModelViewSet):
 
 
     def get_view_name(self):
+        if self.detail:
             return "Device"
+        
+        return 'Devices'

app/app/settings.py

@@ -53,6 +53,8 @@ INSTALLED_APPS = [
     'access.apps.AccessConfig',
     'itam.apps.ItamConfig',
     'settings.apps.SettingsConfig',
+    'drf_spectacular',
+    'drf_spectacular_sidecar'
 ]
 
 MIDDLEWARE = [
@@ -201,7 +203,19 @@ if API_ENABLED:
         #     'rest_framework_json_api.renderers.JSONRenderer',
         # ),
         # 'TEST_REQUEST_DEFAULT_FORMAT': 'vnd.api+json'
-        'TEST_REQUEST_DEFAULT_FORMAT': 'json'
+        'TEST_REQUEST_DEFAULT_FORMAT': 'json',
+        'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
+    }
+
+    SPECTACULAR_SETTINGS = {
+        'TITLE': 'Your Project API',
+        'DESCRIPTION': 'Your project description',
+        'VERSION': '1.0.0',
+        'SERVE_INCLUDE_SCHEMA': False,
+
+        'SWAGGER_UI_DIST': 'SIDECAR',
+        'SWAGGER_UI_FAVICON_HREF': 'SIDECAR',
+        'REDOC_DIST': 'SIDECAR',
     }
 
 DATETIME_FORMAT = 'j N Y H:i:s'

app/app/urls.py

@@ -20,6 +20,8 @@ from django.contrib.auth import views as auth_views
 from django.views.static import serve
 from django.urls import include, path, re_path
 
+from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView
+
 from .views import home
 
 from core.views import history
@@ -46,6 +48,8 @@ if settings.API_ENABLED:
     urlpatterns += [
 
         path("api/", include("api.urls")),
+        path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
+        path('api/swagger/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
     ]
 
 if settings.DEBUG:

requirements.txt

@@ -9,6 +9,13 @@ djangorestframework-jsonapi==7.0.0
 pyyaml==6.0.1
 django-filter==24.2
 
+# OpenAPI Schema
+uritemplate==4.1.1
+coreapi==2.3.3
+
+drf-spectacular==0.27.2
+drf-spectacular-sidecar==2024.6.1
+
 django_split_settings==1.3.1
 
 markdown==3.6