Merge pull request #22434 from netbox-community/22303-openapi-fields-omit

Fixes #22303: Annotate fields & omit parameters in OpenAPI schema

netbox/core/api/schema.py

@@ -14,7 +14,7 @@ from drf_spectacular.plumbing import (
     get_doc,
 )
 from drf_spectacular.types import OpenApiTypes
-from drf_spectacular.utils import Direction
+from drf_spectacular.utils import Direction, OpenApiParameter
 
 from netbox.api.fields import ChoiceField
 from netbox.api.serializers import WritableNestedSerializer
@@ -274,6 +274,37 @@ class NetBoxAutoSchema(AutoSchema):
         writable_class = self.writable_serializers[type(serializer)]
         return writable_class
 
+    def get_override_parameters(self):
+        params = super().get_override_parameters()
+        # Expose the ?fields, ?omit, and ?brief query parameters supported by NetBoxModelViewSet
+        # for all non-bulk GET operations (both list and detail).
+        if not self.is_bulk_action and self.method == 'GET':
+            params = list(params) + [
+                OpenApiParameter(
+                    name='fields',
+                    location=OpenApiParameter.QUERY,
+                    required=False,
+                    type=OpenApiTypes.STR,
+                    description='Comma-separated list of fields to include in the response. Example: `fields=id,name`.',
+                ),
+                OpenApiParameter(
+                    name='omit',
+                    location=OpenApiParameter.QUERY,
+                    required=False,
+                    type=OpenApiTypes.STR,
+                    description='Comma-separated list of fields to exclude from the response. '
+                                'Example: `omit=description,tags`.',
+                ),
+                OpenApiParameter(
+                    name='brief',
+                    location=OpenApiParameter.QUERY,
+                    required=False,
+                    type=OpenApiTypes.BOOL,
+                    description='Return only brief fields for each object.',
+                ),
+            ]
+        return params
+
     def get_filter_backends(self):
         # bulk operations don't have filter params
         if self.is_bulk_action: