chore: improve API docs for Provider endpoints (#8723)

Co-authored-by: Víctor Fernández Poyatos <victor@prowler.com>

api/src/backend/api/filters.py

@@ -220,10 +220,31 @@ class MembershipFilter(FilterSet):
 
 
 class ProviderFilter(FilterSet):
-    inserted_at = DateFilter(field_name="inserted_at", lookup_expr="date")
-    updated_at = DateFilter(field_name="updated_at", lookup_expr="date")
-    connected = BooleanFilter()
+    inserted_at = DateFilter(
+        field_name="inserted_at",
+        lookup_expr="date",
+        help_text="""Filter by date when the provider was added
+        (format: YYYY-MM-DD)""",
+    )
+    updated_at = DateFilter(
+        field_name="updated_at",
+        lookup_expr="date",
+        help_text="""Filter by date when the provider was updated
+        (format: YYYY-MM-DD)""",
+    )
+    connected = BooleanFilter(
+        help_text="""Filter by connection status. Set to True to return only
+        connected providers, or False to return only providers with failed
+        connections. If not specified, both connected and failed providers are
+        included. Providers with no connection attempt (status is null) are
+        excluded from this filter."""
+    )
     provider = ChoiceFilter(choices=Provider.ProviderChoices.choices)
+    provider__in = ChoiceInFilter(
+        field_name="provider",
+        choices=Provider.ProviderChoices.choices,
+        lookup_expr="in",
+    )
 
     class Meta:
         model = Provider
@@ -649,8 +670,16 @@ class LatestFindingFilter(CommonFindingFilters):
 
 
 class ProviderSecretFilter(FilterSet):
-    inserted_at = DateFilter(field_name="inserted_at", lookup_expr="date")
-    updated_at = DateFilter(field_name="updated_at", lookup_expr="date")
+    inserted_at = DateFilter(
+        field_name="inserted_at",
+        lookup_expr="date",
+        help_text="Filter by date when the secret was added (format: YYYY-MM-DD)",
+    )
+    updated_at = DateFilter(
+        field_name="updated_at",
+        lookup_expr="date",
+        help_text="Filter by date when the secret was updated (format: YYYY-MM-DD)",
+    )
     provider = UUIDFilter(field_name="provider__id", lookup_expr="exact")
 
     class Meta:

api/src/backend/api/specs/v1.yaml

@@ -4642,6 +4642,12 @@ paths:
         name: filter[connected]
         schema:
           type: boolean
+        description: |-
+          Filter by connection status. Set to True to return only
+                  connected providers, or False to return only providers with failed
+                  connections. If not specified, both connected and failed providers are
+                  included. Providers with no connection attempt (status is null) are
+                  excluded from this filter.
       - in: query
         name: filter[id]
         schema:
@@ -4662,6 +4668,9 @@ paths:
         schema:
           type: string
           format: date
+        description: |-
+          Filter by date when the provider was added
+                  (format: YYYY-MM-DD)
       - in: query
         name: filter[inserted_at__gte]
         schema:
@@ -4697,7 +4706,22 @@ paths:
           type: array
           items:
             type: string
-        description: Multiple values may be separated by commas.
+            enum:
+            - aws
+            - azure
+            - gcp
+            - github
+            - kubernetes
+            - m365
+        description: |-
+          Multiple values may be separated by commas.
+
+          * `aws` - AWS
+          * `azure` - Azure
+          * `gcp` - GCP
+          * `kubernetes` - Kubernetes
+          * `m365` - M365
+          * `github` - GitHub
         explode: false
         style: form
       - name: filter[search]
@@ -4728,6 +4752,9 @@ paths:
         schema:
           type: string
           format: date
+        description: |-
+          Filter by date when the provider was updated
+                  (format: YYYY-MM-DD)
       - in: query
         name: filter[updated_at__gte]
         schema:
@@ -5018,6 +5045,7 @@ paths:
         schema:
           type: string
           format: date
+        description: 'Filter by date when the secret was added (format: YYYY-MM-DD)'
       - in: query
         name: filter[name]
         schema:
@@ -5042,6 +5070,7 @@ paths:
         schema:
           type: string
           format: date
+        description: 'Filter by date when the secret was updated (format: YYYY-MM-DD)'
       - name: page[number]
         required: false
         in: query
@@ -12099,6 +12128,8 @@ components:
                 alias:
                   type: string
                   nullable: true
+                  description: Human readable name to identify the provider, e.g.
+                    'Production AWS Account', 'Dev Environment'
                   maxLength: 100
                   minLength: 3
       required:
@@ -13140,6 +13171,8 @@ components:
             alias:
               type: string
               nullable: true
+              description: Human readable name to identify the provider, e.g. 'Production
+                AWS Account', 'Dev Environment'
               maxLength: 100
               minLength: 3
             provider:
@@ -13151,17 +13184,21 @@ components:
               - m365
               - github
               type: string
+              x-spec-enum-id: 4c1e219dad1cc0e7
               description: |-
+                Type of provider to create.
+
                 * `aws` - AWS
                 * `azure` - Azure
                 * `gcp` - GCP
                 * `kubernetes` - Kubernetes
                 * `m365` - M365
                 * `github` - GitHub
-              x-spec-enum-id: 4c1e219dad1cc0e7
             uid:
               type: string
               title: Unique identifier for the provider, set by the provider
+              description: Unique identifier for the provider, set by the provider,
+                e.g. AWS account ID, Azure subscription ID, GCP project ID, etc.
               maxLength: 250
               minLength: 3
           required:
@@ -13188,6 +13225,8 @@ components:
                 alias:
                   type: string
                   nullable: true
+                  description: Human readable name to identify the provider, e.g.
+                    'Production AWS Account', 'Dev Environment'
                   maxLength: 100
                   minLength: 3
                 provider:
@@ -13199,18 +13238,22 @@ components:
                   - m365
                   - github
                   type: string
+                  x-spec-enum-id: 4c1e219dad1cc0e7
                   description: |-
+                    Type of provider to create.
+
                     * `aws` - AWS
                     * `azure` - Azure
                     * `gcp` - GCP
                     * `kubernetes` - Kubernetes
                     * `m365` - M365
                     * `github` - GitHub
-                  x-spec-enum-id: 4c1e219dad1cc0e7
                 uid:
                   type: string
                   minLength: 3
                   title: Unique identifier for the provider, set by the provider
+                  description: Unique identifier for the provider, set by the provider,
+                    e.g. AWS account ID, Azure subscription ID, GCP project ID, etc.
                   maxLength: 250
               required:
               - uid

api/src/backend/api/v1/serializers.py

@@ -909,6 +909,17 @@ class ProviderCreateSerializer(RLSSerializer, BaseWriteSerializer):
             "uid",
             # "scanner_args"
         ]
+        extra_kwargs = {
+            "alias": {
+                "help_text": "Human readable name to identify the provider, e.g. 'Production AWS Account', 'Dev Environment'",
+            },
+            "provider": {
+                "help_text": "Type of provider to create.",
+            },
+            "uid": {
+                "help_text": "Unique identifier for the provider, set by the provider, e.g. AWS account ID, Azure subscription ID, GCP project ID, etc.",
+            },
+        }
 
 
 class ProviderUpdateSerializer(BaseWriteSerializer):
@@ -923,6 +934,11 @@ class ProviderUpdateSerializer(BaseWriteSerializer):
             "alias",
             # "scanner_args"
         ]
+        extra_kwargs = {
+            "alias": {
+                "help_text": "Human readable name to identify the provider, e.g. 'Production AWS Account', 'Dev Environment'",
+            }
+        }
 
 
 # Scans