Use drf_yasg to generate swagger

drf_yasg provides more complete swagger output, allowing for generation
of usable clients.

Some custom work was needed to accommodate Netbox's custom field
serializers, and to provide x-nullable attributes where appropriate.

netbox/utilities/custom_inspectors.py

@@ -0,0 +1,60 @@
+from drf_yasg import openapi
+from drf_yasg.inspectors import FieldInspector, NotHandled, PaginatorInspector
+from rest_framework.fields import ChoiceField
+
+from extras.api.customfields import CustomFieldsSerializer
+from utilities.api import ChoiceFieldSerializer
+
+
+class CustomChoiceFieldInspector(FieldInspector):
+    def field_to_swagger_object(self, field, swagger_object_type, use_references, **kwargs):
+        # this returns a callable which extracts title, description and other stuff
+        # https://drf-yasg.readthedocs.io/en/stable/_modules/drf_yasg/inspectors/base.html#FieldInspector._get_partial_types
+        SwaggerType, _ = self._get_partial_types(field, swagger_object_type, use_references, **kwargs)
+
+        if isinstance(field, ChoiceFieldSerializer):
+            value_schema = openapi.Schema(type=openapi.TYPE_INTEGER)
+
+            if set([None] + list(field._choices.keys())) == {None, True, False}:
+                # Special case face and connection_status because the only keys for choices are True and False,
+                # but the underlying field is still a NullBooleanField
+                value_schema = openapi.Schema(type=openapi.TYPE_BOOLEAN)
+                value_schema['x-nullable'] = True
+
+            schema = SwaggerType(type=openapi.TYPE_OBJECT, required=["label", "value"], properties={
+                "label": openapi.Schema(type=openapi.TYPE_STRING),
+                "value": value_schema
+            })
+
+            return schema
+
+        elif isinstance(field, CustomFieldsSerializer):
+            schema = SwaggerType(type=openapi.TYPE_OBJECT)
+            return schema
+
+        return NotHandled
+
+
+class NullableBooleanFieldInspector(FieldInspector):
+    def process_result(self, result, method_name, obj, **kwargs):
+
+        if isinstance(result, openapi.Schema) and isinstance(obj, ChoiceField) and result.type == 'boolean':
+            keys = obj.choices.keys()
+            if set(keys) == {None, True, False}:
+                result['x-nullable'] = True
+                result.type = 'boolean'
+
+        return result
+
+
+class NullablePaginatorInspector(PaginatorInspector):
+    def process_result(self, result, method_name, obj, **kwargs):
+        if method_name == 'get_paginated_response' and isinstance(result, openapi.Schema):
+            next = result.properties['next']
+            if isinstance(next, openapi.Schema):
+                next['x-nullable'] = True
+            previous = result.properties['previous']
+            if isinstance(previous, openapi.Schema):
+                previous['x-nullable'] = True
+
+        return result