chore(api): clean up API spec (apache#24838)

preset-io · Jul 31, 2023 · 14a27b1 · 14a27b1
1 parent 5f10307
commit 14a27b1
Show file tree

Hide file tree

Showing 49 changed files with 402 additions and 426 deletions.
diff --git a/superset/advanced_data_type/api.py b/superset/advanced_data_type/api.py
@@ -61,11 +61,12 @@ class AdvancedDataTypeRestApi(BaseSupersetApi):
     )
     @rison(advanced_data_type_convert_schema)
     def get(self, **kwargs: Any) -> Response:
-        """Returns a AdvancedDataTypeResponse object populated with the passed in args
+        """Return an AdvancedDataTypeResponse object populated with the passed in args.
         ---
         get:
-          summary: >-
-            Returns a AdvancedDataTypeResponse object populated with the passed in args.
+          summary: Return an AdvancedDataTypeResponse
+          description: >-
+            Returns an AdvancedDataTypeResponse object populated with the passed in args.
           parameters:
           - in: query
             name: q
@@ -118,11 +119,10 @@ def get(self, **kwargs: Any) -> Response:
         log_to_statsd=False,  # pylint: disable-arguments-renamed
     )
     def get_types(self) -> Response:
-        """Returns a list of available advanced data types
+        """Return a list of available advanced data types.
         ---
         get:
-          description: >-
-            Returns a list of available advanced data types.
+          summary: Return a list of available advanced data types
           responses:
             200:
               description: >-
@@ -144,5 +144,4 @@ def get_types(self) -> Response:
             500:
               $ref: '#/components/responses/500'
         """
-
         return self.response(200, result=list(ADVANCED_DATA_TYPES.keys()))
diff --git a/superset/annotation_layers/annotations/api.py b/superset/annotation_layers/annotations/api.py
@@ -139,11 +139,10 @@ def _apply_layered_relation_to_rison(  # pylint: disable=invalid-name
     def get_list(  # pylint: disable=arguments-differ
         self, pk: int, **kwargs: Any
     ) -> Response:
-        """Get a list of annotations
+        """Get a list of annotations.
         ---
         get:
-          description: >-
-            Get a list of annotations
+          summary: Get a list of annotations
           parameters:
           - in: path
             schema:
@@ -200,11 +199,10 @@ def get_list(  # pylint: disable=arguments-differ
     def get(  # pylint: disable=arguments-differ
         self, pk: int, annotation_id: int, **kwargs: Any
     ) -> Response:
-        """Get item from Model
+        """Get item from model.
         ---
         get:
-          description: >-
-            Get an item model
+          summary: Get an item model
           parameters:
           - in: path
             schema:
@@ -256,11 +254,10 @@ def get(  # pylint: disable=arguments-differ
     @permission_name("post")
     @requires_json
     def post(self, pk: int) -> Response:  # pylint: disable=arguments-differ
-        """Creates a new Annotation
+        """Create a new annotation.
         ---
         post:
-          description: >-
-            Create a new Annotation
+          summary: Create a new annotation
           parameters:
           - in: path
             schema:
@@ -326,11 +323,10 @@ def post(self, pk: int) -> Response:  # pylint: disable=arguments-differ
     def put(  # pylint: disable=arguments-differ
         self, pk: int, annotation_id: int
     ) -> Response:
-        """Updates an Annotation
+        """Update an annotation.
         ---
         put:
-          description: >-
-            Update an annotation
+          summary: Update an annotation
           parameters:
           - in: path
             schema:
@@ -400,11 +396,10 @@ def put(  # pylint: disable=arguments-differ
     def delete(  # pylint: disable=arguments-differ
         self, pk: int, annotation_id: int
     ) -> Response:
-        """Deletes an Annotation
+        """Delete an annotation.
         ---
         delete:
-          description: >-
-            Delete an annotation
+          summary: Delete an annotation
           parameters:
           - in: path
             schema:
@@ -453,11 +448,10 @@ def delete(  # pylint: disable=arguments-differ
     @statsd_metrics
     @rison(get_delete_ids_schema)
     def bulk_delete(self, **kwargs: Any) -> Response:
-        """Delete bulk Annotation layers
+        """Bulk delete annotation layers.
         ---
         delete:
-          description: >-
-            Deletes multiple annotation in a bulk operation.
+          summary: Bulk delete annotation layers
           parameters:
           - in: path
             schema:

diff --git a/superset/annotation_layers/annotations/schemas.py b/superset/annotation_layers/annotations/schemas.py
@@ -23,23 +23,24 @@
 from superset.utils import core as utils
 
 openapi_spec_methods_override = {
-    "get": {"get": {"description": "Get an Annotation layer"}},
+    "get": {"get": {"summary": "Get an annotation layer"}},
     "get_list": {
         "get": {
-            "description": "Get a list of Annotation layers, use Rison or JSON "
+            "summary": "Get a list of annotation layers",
+            "description": "Gets a list of annotation layers, use Rison or JSON "
             "query parameters for filtering, sorting,"
             " pagination and for selecting specific"
             " columns and metadata.",
         }
     },
-    "post": {"post": {"description": "Create an Annotation layer"}},
-    "put": {"put": {"description": "Update an Annotation layer"}},
-    "delete": {"delete": {"description": "Delete Annotation layer"}},
+    "post": {"post": {"summary": "Create an annotation layer"}},
+    "put": {"put": {"summary": "Update an annotation layer"}},
+    "delete": {"delete": {"summary": "Delete annotation layer"}},
+    "info": {"get": {"summary": "Get metadata information about this API resource"}},
 }
 
 get_delete_ids_schema = {"type": "array", "items": {"type": "integer"}}
 
-
 annotation_start_dttm = "The annotation start date time"
 annotation_end_dttm = "The annotation end date time"
 annotation_layer = "The annotation layer id"

diff --git a/superset/annotation_layers/api.py b/superset/annotation_layers/api.py
@@ -117,11 +117,10 @@ class AnnotationLayerRestApi(BaseSupersetModelRestApi):
     )
     @permission_name("delete")
     def delete(self, pk: int) -> Response:
-        """Delete an annotation layer
+        """Delete an annotation layer.
         ---
         delete:
-          description: >-
-            Delete an annotation layer
+          summary: Delete an annotation layer
           parameters:
           - in: path
             schema:
@@ -172,11 +171,10 @@ def delete(self, pk: int) -> Response:
     )
     @requires_json
     def post(self) -> Response:
-        """Creates a new Annotation Layer
+        """Create a new annotation layer.
         ---
         post:
-          description: >-
-            Create a new Annotation
+          summary: Create a new annotation layer
           requestBody:
             description: Annotation Layer schema
             required: true
@@ -237,11 +235,10 @@ def post(self) -> Response:
     )
     @requires_json
     def put(self, pk: int) -> Response:
-        """Updates an Annotation Layer
+        """Update an annotation layer.
         ---
         put:
-          description: >-
-            Update an annotation layer
+          summary: Update an annotation layer
           parameters:
           - in: path
             schema:
@@ -308,11 +305,10 @@ def put(self, pk: int) -> Response:
         log_to_statsd=False,
     )
     def bulk_delete(self, **kwargs: Any) -> Response:
-        """Delete bulk Annotation layers
+        """Bulk delete annotation layers.
         ---
         delete:
-          description: >-
-            Deletes multiple annotation layers in a bulk operation.
+          summary: Delete multiple annotation layers in a bulk operation
           parameters:
           - in: query
             name: q

diff --git a/superset/annotation_layers/schemas.py b/superset/annotation_layers/schemas.py
@@ -18,18 +18,20 @@
 from marshmallow.validate import Length
 
 openapi_spec_methods_override = {
-    "get": {"get": {"description": "Get an Annotation layer"}},
+    "get": {"get": {"summary": "Get an annotation layer"}},
     "get_list": {
         "get": {
-            "description": "Get a list of Annotation layers, use Rison or JSON "
+            "summary": "Get a list of annotation layers",
+            "description": "Gets a list of annotation layers, use Rison or JSON "
             "query parameters for filtering, sorting,"
             " pagination and for selecting specific"
             " columns and metadata.",
         }
     },
-    "post": {"post": {"description": "Create an Annotation layer"}},
-    "put": {"put": {"description": "Update an Annotation layer"}},
-    "delete": {"delete": {"description": "Delete Annotation layer"}},
+    "post": {"post": {"summary": "Create an annotation layer"}},
+    "put": {"put": {"summary": "Update an annotation layer"}},
+    "delete": {"delete": {"summary": "Delete annotation layer"}},
+    "info": {"get": {"summary": "Get metadata information about this API resource"}},
 }
 
 get_delete_ids_schema = {"type": "array", "items": {"type": "integer"}}

diff --git a/superset/async_events/api.py b/superset/async_events/api.py
@@ -39,10 +39,11 @@ class AsyncEventsRestApi(BaseSupersetApi):
     @permission_name("list")
     def events(self) -> Response:
         """
-        Reads off of the Redis async events stream, using the user's JWT token and
+        Read off of the Redis async events stream, using the user's JWT token and
         optional query params for last event received.
         ---
         get:
+          summary: Read off of the Redis events stream
           description: >-
             Reads off of the Redis events stream, using the user's JWT token and
             optional query params for last event received.

diff --git a/superset/available_domains/api.py b/superset/available_domains/api.py
@@ -48,13 +48,12 @@ class AvailableDomainsRestApi(BaseSupersetApi):
     )
     def get(self) -> Response:
         """
-        Returns the list of available Superset Webserver domains (if any)
+        Get the list of available Superset Webserver domains (if any)
         defined in config. This enables charts embedded in other apps to
         leverage domain sharding if appropriately configured.
         ---
         get:
-          description: >-
-            Get all available domains
+          summary: Get all available domains
           responses:
             200:
               description: a list of available domains

diff --git a/superset/cachekeys/api.py b/superset/cachekeys/api.py
@@ -51,14 +51,14 @@ class CacheRestApi(BaseSupersetModelRestApi):
     @event_logger.log_this_with_context(log_to_statsd=False)
     def invalidate(self) -> Response:
         """
-        Takes a list of datasources, finds the associated cache records and
-        invalidates them and removes the database records
-
+        Take a list of datasources, find and invalidate the associated cache records
+        and remove the database records.
         ---
         post:
+          summary: Invalidate cache records and remove the database records
           description: >-
-            Takes a list of datasources, finds the associated cache records and
-            invalidates them and removes the database records
+            Takes a list of datasources, finds and invalidates the associated cache
+            records and removes the database records.
           requestBody:
             description: >-
               A list of datasources uuid or the tuples of database and datasource names