docs(api): document the inventory endpoint

!24 #55

app/api/serializers/itam/inventory.py

@@ -0,0 +1,73 @@
+from django.urls import reverse
+
+from itam.models.device import Device
+from rest_framework import serializers
+
+
+
+
+class InventorySerializer(serializers.Serializer):
+    """ Serializer for Inventory Upload """
+
+
+    class DetailsSerializer(serializers.Serializer):
+
+        name = serializers.CharField(
+            help_text = 'Host name',
+            required = True
+        )
+
+        serial_number = serializers.CharField(
+            help_text = 'Devices serial number',
+            required = True
+        )
+
+        uuid = serializers.CharField(
+            help_text = 'Device system UUID',
+            required = True
+        )
+
+
+    class OperatingSystemSerializer(serializers.Serializer):
+
+        name = serializers.CharField(
+            help_text='Name of the operating system installed on the device',
+            required = True,
+        )
+
+        version_major = serializers.IntegerField(
+            help_text='Major semver version number of the OS version',
+            required = True,
+        )
+
+        version = serializers.CharField(
+            help_text='semver version number of the OS',
+            required = True
+        )
+
+
+    class SoftwareSerializer(serializers.Serializer):
+
+        name = serializers.CharField(
+            help_text='Name of the software',
+            required = True
+        )
+
+        category = serializers.CharField(
+            help_text='Category of the software',
+            default = None,
+            required = False
+        )
+
+        version = serializers.CharField(
+            default = None,
+            help_text='semver version number of the software',
+            required = False
+        )
+
+
+    details = DetailsSerializer()
+
+    os = OperatingSystemSerializer()
+
+    software = SoftwareSerializer(many = True)

app/api/views/itam/inventory.py

@@ -5,6 +5,8 @@ import re
 from django.http import Http404, JsonResponse
 from django.utils import timezone
 
+from drf_spectacular.utils import extend_schema, OpenApiExample, OpenApiTypes, OpenApiResponse, OpenApiParameter
+
 from rest_framework import generics, views
 from rest_framework.response import Response
 
@@ -12,6 +14,7 @@ from access.mixin import OrganizationMixin
 from access.models import Organization
 
 from api.views.mixin import OrganizationPermissionAPI
+from api.serializers.itam.inventory import InventorySerializer
 
 from core.http.common import Http
 
@@ -38,20 +41,44 @@ class InventoryPermissions(OrganizationPermissionAPI):
 
 class Collect(OrganizationPermissionAPI, views.APIView):
 
-    # permission_classes = [
-    #     InventoryPermissions
-    # ]
-
     queryset = Device.objects.all()
 
 
+    @extend_schema(
+        summary = "Upload a device's inventory",
+        description = """After inventorying a device, it's inventory file, `.json` is uploaded to this endpoint.
+If the device does not exist, it will be created. If the device does exist the existing
+device will be updated with the information within the inventory.
+
+matching for an existing device is by slug which is the hostname converted to lower case
+letters. This conversion is automagic.
+
+**NOTE:** _for device creation, the API user must have user setting 'Default Organization'. Without
+this setting populated, no device will be created and the endpoint will return HTTP/403_
+
+## Permissions
+
+- `itam.add_device` Required to upload inventory
+        """,
+
+        methods=["POST"],
+        parameters = None,
+        tags = ['device', 'inventory',],
+        request = InventorySerializer,
+        responses = {
+            200: OpenApiResponse(description='Inventory updated an existing device'),
+            201: OpenApiResponse(description='Inventory created a new device'),
+            400: OpenApiResponse(description='Inventory is invalid'),
+            401: OpenApiResponse(description='User Not logged in'),
+            403: OpenApiResponse(description='User is missing permission or in different organization'),
+            500: OpenApiResponse(description='Exception occured. View server logs for the Stack Trace'),
+        }
+    )
     def post(self, request, *args, **kwargs):
 
 
         data = json.loads(request.body)
 
-        # data = self.request.data
-
         device = None
 
         self.default_organization = UserSettings.objects.get(user=request.user).default_organization

app/app/settings.py

@@ -223,8 +223,33 @@ if API_ENABLED:
     }
 
     SPECTACULAR_SETTINGS = {
-        'TITLE': 'Your Project API',
-        'DESCRIPTION': 'Your project description',
+        'TITLE': 'ITSM API',
+        'DESCRIPTION': """This UI is intended to serve as the API documentation.
+
+## Authentication
+
+Authentication with the api is via Token. The token is placed in header `Authorization` with a value of `Token <Your Token>`.
+
+## Token Generation
+
+To generate a token, run `python3 manage.py drf_create_token <username>` from the CLI.
+
+## Examples
+
+curl:
+- Simple API Request: `curl -X GET <url>/api/ -H 'Authorization: Token <token>'`
+
+- Post an Inventory File:
+
+    ``` bash
+    curl --header "Content-Type: application/json" \\
+    --header "Authorization: Token <token>" \\
+    --request POST \\
+    --data @<path to inventory file>/<file name>.json \\
+    <url>/api/device/inventory
+    ```
+
+        """,
         'VERSION': '1.0.0',
         'SERVE_INCLUDE_SCHEMA': False,