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

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: >-
+          summary: Return an AdvancedDataTypeResponse
-            Returns a AdvancedDataTypeResponse object populated with the passed in args.
+          description: >-
+            Returns an AdvancedDataTypeResponse object populated with the passed in args.
           parameters:
           - in: query
             name: q
@@ -118,11 +119,10 @@ class AdvancedDataTypeRestApi(BaseSupersetApi):
         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: >-
+          summary: Return a list of available advanced data types
-            Returns a list of available advanced data types.
           responses:
             200:
               description: >-
@@ -144,5 +144,4 @@ class AdvancedDataTypeRestApi(BaseSupersetApi):
             500:
               $ref: '#/components/responses/500'
         """
-
         return self.response(200, result=list(ADVANCED_DATA_TYPES.keys()))

superset/annotation_layers/annotations/api.py

@@ -139,11 +139,10 @@ class AnnotationRestApi(BaseSupersetModelRestApi):
     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: >-
+          summary: Get a list of annotations
-            Get a list of annotations
           parameters:
           - in: path
             schema:
@@ -200,11 +199,10 @@ class AnnotationRestApi(BaseSupersetModelRestApi):
     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: >-
+          summary: Get an item model
-            Get an item model
           parameters:
           - in: path
             schema:
@@ -256,11 +254,10 @@ class AnnotationRestApi(BaseSupersetModelRestApi):
     @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: >-
+          summary: Create a new annotation
-            Create a new Annotation
           parameters:
           - in: path
             schema:
@@ -326,11 +323,10 @@ class AnnotationRestApi(BaseSupersetModelRestApi):
     def put(  # pylint: disable=arguments-differ
         self, pk: int, annotation_id: int
     ) -> Response:
-        """Updates an Annotation
+        """Update an annotation.
         ---
         put:
-          description: >-
+          summary: Update an annotation
-            Update an annotation
           parameters:
           - in: path
             schema:
@@ -400,11 +396,10 @@ class AnnotationRestApi(BaseSupersetModelRestApi):
     def delete(  # pylint: disable=arguments-differ
         self, pk: int, annotation_id: int
     ) -> Response:
-        """Deletes an Annotation
+        """Delete an annotation.
         ---
         delete:
-          description: >-
+          summary: Delete an annotation
-            Delete an annotation
           parameters:
           - in: path
             schema:
@@ -453,11 +448,10 @@ class AnnotationRestApi(BaseSupersetModelRestApi):
     @statsd_metrics
     @rison(get_delete_ids_schema)
     def bulk_delete(self, **kwargs: Any) -> Response:
-        """Delete bulk Annotation layers
+        """Bulk delete annotation layers.
         ---
         delete:
-          description: >-
+          summary: Bulk delete annotation layers
-            Deletes multiple annotation in a bulk operation.
           parameters:
           - in: path
             schema:

superset/annotation_layers/annotations/schemas.py

@@ -23,23 +23,24 @@ from superset.exceptions import SupersetException
 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"}},
+    "post": {"post": {"summary": "Create an annotation layer"}},
-    "put": {"put": {"description": "Update an Annotation layer"}},
+    "put": {"put": {"summary": "Update an annotation layer"}},
-    "delete": {"delete": {"description": "Delete 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"

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

superset/annotation_layers/schemas.py

@@ -18,18 +18,20 @@ from marshmallow import fields, Schema
 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"}},
+    "post": {"post": {"summary": "Create an annotation layer"}},
-    "put": {"put": {"description": "Update an Annotation layer"}},
+    "put": {"put": {"summary": "Update an annotation layer"}},
-    "delete": {"delete": {"description": "Delete 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"}}

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.

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: >-
+          summary: Get all available domains
-            Get all available domains
           responses:
             200:
               description: a list of available domains

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
+        Take a list of datasources, find and invalidate the associated cache records
-        invalidates them and removes the database 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
+            Takes a list of datasources, finds and invalidates the associated cache
-            invalidates them and removes the database records
+            records and removes the database records.
           requestBody:
             description: >-
               A list of datasources uuid or the tuples of database and datasource names

superset/charts/api.py

@@ -285,11 +285,10 @@ class ChartRestApi(BaseSupersetModelRestApi):
     )
     @requires_json
     def post(self) -> Response:
-        """Creates a new Chart
+        """Create a new chart.
         ---
         post:
-          description: >-
+          summary: Create a new chart
-            Create a new Chart.
           requestBody:
             description: Chart schema
             required: true
@@ -351,11 +350,10 @@ class ChartRestApi(BaseSupersetModelRestApi):
     )
     @requires_json
     def put(self, pk: int) -> Response:
-        """Changes a Chart
+        """Update a chart.
         ---
         put:
-          description: >-
+          summary: Update a chart
-            Changes a Chart.
           parameters:
           - in: path
             schema:
@@ -427,11 +425,10 @@ class ChartRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def delete(self, pk: int) -> Response:
-        """Deletes a Chart
+        """Delete a chart.
         ---
         delete:
-          description: >-
+          summary: Delete a chart
-            Deletes a Chart.
           parameters:
           - in: path
             schema:
@@ -484,11 +481,10 @@ class ChartRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def bulk_delete(self, **kwargs: Any) -> Response:
-        """Delete bulk Charts
+        """Bulk delete charts.
         ---
         delete:
-          description: >-
+          summary: Bulk delete charts
-            Deletes multiple Charts in a bulk operation.
           parameters:
           - in: query
             name: q
@@ -544,10 +540,10 @@ class ChartRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def cache_screenshot(self, pk: int, **kwargs: Any) -> WerkzeugResponse:
-        """
+        """Compute and cache a screenshot.
         ---
         get:
-          description: Compute and cache a screenshot.
+          summary: Compute and cache a screenshot
           parameters:
           - in: path
             schema:
@@ -616,10 +612,10 @@ class ChartRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def screenshot(self, pk: int, digest: str) -> WerkzeugResponse:
-        """Get Chart screenshot
+        """Get a computed screenshot from cache.
         ---
         get:
-          description: Get a computed screenshot from cache.
+          summary: Get a computed screenshot from cache
           parameters:
           - in: path
             schema:
@@ -670,9 +666,10 @@ class ChartRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def thumbnail(self, pk: int, digest: str, **kwargs: Any) -> WerkzeugResponse:
-        """Get Chart thumbnail
+        """Compute or get already computed chart thumbnail from cache.
         ---
         get:
+          summary: Get chart thumbnail
           description: Compute or get already computed chart thumbnail from cache.
           parameters:
           - in: path
@@ -757,11 +754,10 @@ class ChartRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def export(self, **kwargs: Any) -> Response:
-        """Export charts
+        """Download multiple charts as YAML files.
         ---
         get:
-          description: >-
+          summary: Download multiple charts as YAML files
-            Exports multiple charts and downloads them as YAML files
           parameters:
           - in: query
             name: q
@@ -822,11 +818,10 @@ class ChartRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def favorite_status(self, **kwargs: Any) -> Response:
-        """Favorite stars for Charts
+        """Check favorited charts for current user.
         ---
         get:
-          description: >-
+          summary: Check favorited charts for current user
-            Check favorited dashboards for current user
           parameters:
           - in: query
             name: q
@@ -871,11 +866,10 @@ class ChartRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def add_favorite(self, pk: int) -> Response:
-        """Marks the chart as favorite
+        """Mark the chart as favorite for the current user.
         ---
         post:
-          description: >-
+          summary: Mark the chart as favorite for the current user
-            Marks the chart as favorite for the current user
           parameters:
           - in: path
             schema:
@@ -915,11 +909,10 @@ class ChartRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def remove_favorite(self, pk: int) -> Response:
-        """Remove the chart from the user favorite list
+        """Remove the chart from the user favorite list.
         ---
         delete:
-          description: >-
+          summary: Remove the chart from the user favorite list
-            Remove the chart from the user favorite list
           parameters:
           - in: path
             schema:
@@ -959,11 +952,10 @@ class ChartRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def warm_up_cache(self) -> Response:
-        """
+        """Warm up the cache for the chart.
         ---
         put:
-          summary: >-
+          summary: Warm up the cache for the chart
-            Warms up the cache for the chart
           description: >-
             Warms up the cache for the chart.
             Note for slices a force refresh occurs.
@@ -1015,9 +1007,10 @@ class ChartRestApi(BaseSupersetModelRestApi):
     )
     @requires_form_data
     def import_(self) -> Response:
-        """Import chart(s) with associated datasets and databases
+        """Import chart(s) with associated datasets and databases.
         ---
         post:
+          summary: Import chart(s) with associated datasets and databases
           requestBody:
             required: true
             content:

superset/charts/data/api.py

@@ -68,10 +68,11 @@ class ChartDataRestApi(ChartRestApi):
     )
     def get_data(self, pk: int) -> Response:
         """
-        Takes a chart ID and uses the query context stored when the chart was saved
+        Take a chart ID and uses the query context stored when the chart was saved
         to return payload data response.
         ---
         get:
+          summary: Return payload data response for a chart
           description: >-
             Takes a chart ID and uses the query context stored when the chart was saved
             to return payload data response.
@@ -180,10 +181,11 @@ class ChartDataRestApi(ChartRestApi):
     )
     def data(self) -> Response:
         """
-        Takes a query context constructed in the client and returns payload
+        Take a query context constructed in the client and return payload
-        data response for the given query.
+        data response for the given query
         ---
         post:
+          summary: Return payload data response for the given query
           description: >-
             Takes a query context constructed in the client and returns payload data
             response for the given query.
@@ -267,10 +269,11 @@ class ChartDataRestApi(ChartRestApi):
     )
     def data_from_cache(self, cache_key: str) -> Response:
         """
-        Takes a query context cache key and returns payload
+        Take a query context cache key and return payload
         data response for the given query.
         ---
         get:
+          summary: Return payload data response for the given query
           description: >-
             Takes a query context cache key and returns payload data
             response for the given query.

superset/charts/schemas.py

@@ -123,23 +123,17 @@ owners_name_description = "Name of an owner of the chart."
 certified_by_description = "Person or group that has certified this chart"
 certification_details_description = "Details of the certification"
 
-#
-# OpenAPI method specification overrides
-#
 openapi_spec_methods_override = {
-    "get": {"get": {"description": "Get a chart detail information."}},
+    "get": {"get": {"summary": "Get a chart detail information"}},
     "get_list": {
         "get": {
-            "description": "Get a list of charts, use Rison or JSON query "
+            "summary": "Get a list of charts",
+            "description": "Gets a list of charts, use Rison or JSON query "
             "parameters for filtering, sorting, pagination and "
             " for selecting specific columns and metadata.",
         }
     },
-    "info": {
+    "info": {"get": {"summary": "Get metadata information about this API resource"}},
-        "get": {
-            "description": "Several metadata information about chart API endpoints.",
-        }
-    },
     "related": {
         "get": {
             "description": "Get a list of all possible owners for a chart. "

superset/css_templates/api.py

@@ -97,11 +97,10 @@ class CssTemplateRestApi(BaseSupersetModelRestApi):
     )
     @rison(get_delete_ids_schema)
     def bulk_delete(self, **kwargs: Any) -> Response:
-        """Delete bulk CSS Templates
+        """Bulk delete CSS templates.
         ---
         delete:
-          description: >-
+          summary: Bulk delete CSS templates
-            Deletes multiple css templates in a bulk operation.
           parameters:
           - in: query
             name: q

superset/css_templates/schemas.py

@@ -16,18 +16,20 @@
 # under the License.
 
 openapi_spec_methods_override = {
-    "get": {"get": {"description": "Get a CSS template"}},
+    "get": {"get": {"summary": "Get a CSS template"}},
     "get_list": {
         "get": {
-            "description": "Get a list of CSS templates, use Rison or JSON "
+            "summary": "Get a list of CSS templates",
+            "description": "Gets a list of CSS templates, use Rison or JSON "
             "query parameters for filtering, sorting,"
             " pagination and for selecting specific"
             " columns and metadata.",
         }
     },
-    "post": {"post": {"description": "Create a CSS template"}},
+    "post": {"post": {"summary": "Create a CSS template"}},
-    "put": {"put": {"description": "Update a CSS template"}},
+    "put": {"put": {"summary": "Update a CSS template"}},
-    "delete": {"delete": {"description": "Delete CSS template"}},
+    "delete": {"delete": {"summary": "Delete a CSS template"}},
+    "info": {"get": {"summary": "Get metadata information about this API resource"}},
 }
 
 get_delete_ids_schema = {"type": "array", "items": {"type": "integer"}}

superset/dashboards/api.py

@@ -312,11 +312,10 @@ class DashboardRestApi(BaseSupersetModelRestApi):
         dash: Dashboard,
         add_extra_log_payload: Callable[..., None] = lambda **kwargs: None,
     ) -> Response:
-        """Gets a dashboard
+        """Get a dashboard.
         ---
         get:
-          description: >-
+          summary: Get a dashboard
-            Get a dashboard
           parameters:
           - in: path
             schema:
@@ -367,9 +366,10 @@ class DashboardRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def get_datasets(self, id_or_slug: str) -> Response:
-        """Gets a dashboard's datasets
+        """Get dashboard's datasets.
         ---
         get:
+          summary: Get dashboard's datasets
           description: >-
             Returns a list of a dashboard's datasets. Each dataset includes only
             the information necessary to render the dashboard's charts.
@@ -436,11 +436,10 @@ class DashboardRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def get_charts(self, id_or_slug: str) -> Response:
-        """Gets the chart definitions for a given dashboard
+        """Get a dashboard's chart definitions.
         ---
         get:
-          description: >-
+          summary: Get a dashboard's chart definitions.
-            Get the chart definitions for a given dashboard
           parameters:
           - in: path
             schema:
@@ -494,11 +493,10 @@ class DashboardRestApi(BaseSupersetModelRestApi):
     )
     @requires_json
     def post(self) -> Response:
-        """Creates a new Dashboard
+        """Create a new dashboard.
         ---
         post:
-          description: >-
+          summary: Create a new dashboard
-            Create a new Dashboard.
           requestBody:
             description: Dashboard schema
             required: true
@@ -556,11 +554,10 @@ class DashboardRestApi(BaseSupersetModelRestApi):
     )
     @requires_json
     def put(self, pk: int) -> Response:
-        """Changes a Dashboard
+        """Update a dashboard.
         ---
         put:
-          description: >-
+          summary: Update a dashboard
-            Changes a Dashboard.
           parameters:
           - in: path
             schema:
@@ -641,11 +638,10 @@ class DashboardRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def delete(self, pk: int) -> Response:
-        """Deletes a Dashboard
+        """Delete a dashboard.
         ---
         delete:
-          description: >-
+          summary: Delete a dashboard
-            Deletes a Dashboard.
           parameters:
           - in: path
             schema:
@@ -698,11 +694,10 @@ class DashboardRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def bulk_delete(self, **kwargs: Any) -> Response:
-        """Delete bulk Dashboards
+        """Bulk delete dashboards.
         ---
         delete:
-          description: >-
+          summary: Bulk delete dashboards
-            Deletes multiple Dashboards in a bulk operation.
           parameters:
           - in: query
             name: q
@@ -759,11 +754,10 @@ class DashboardRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def export(self, **kwargs: Any) -> Response:  # pylint: disable=too-many-locals
-        """Export dashboards
+        """Download multiple dashboards as YAML files.
         ---
         get:
-          description: >-
+          summary: Download multiple dashboards as YAML files
-            Exports multiple Dashboards and downloads them as YAML files.
           parameters:
           - in: query
             name: q
@@ -844,11 +838,12 @@ class DashboardRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def thumbnail(self, pk: int, digest: str, **kwargs: Any) -> WerkzeugResponse:
-        """Get Dashboard thumbnail
+        """Compute async or get already computed dashboard thumbnail from cache.
         ---
         get:
+          summary: Get dashboard's thumbnail
           description: >-
-            Compute async or get already computed dashboard thumbnail from cache.
+            Computes async or get already computed dashboard thumbnail from cache.
           parameters:
           - in: path
             schema:
@@ -948,11 +943,10 @@ class DashboardRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def favorite_status(self, **kwargs: Any) -> Response:
-        """Favorite Stars for Dashboards
+        """Check favorited dashboards for current user.
         ---
         get:
-          description: >-
+          summary: Check favorited dashboards for current user
-            Check favorited dashboards for current user
           parameters:
           - in: query
             name: q
@@ -998,11 +992,10 @@ class DashboardRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def add_favorite(self, pk: int) -> Response:
-        """Marks the dashboard as favorite
+        """Mark the dashboard as favorite for the current user.
         ---
         post:
-          description: >-
+          summary: Mark the dashboard as favorite for the current user
-            Marks the dashboard as favorite for the current user
           parameters:
           - in: path
             schema:
@@ -1042,11 +1035,10 @@ class DashboardRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def remove_favorite(self, pk: int) -> Response:
-        """Remove the dashboard from the user favorite list
+        """Remove the dashboard from the user favorite list.
         ---
         delete:
-          description: >-
+          summary: Remove the dashboard from the user favorite list
-            Remove the dashboard from the user favorite list
           parameters:
           - in: path
             schema:
@@ -1085,9 +1077,10 @@ class DashboardRestApi(BaseSupersetModelRestApi):
     )
     @requires_form_data
     def import_(self) -> Response:
-        """Import dashboard(s) with associated charts/datasets/databases
+        """Import dashboard(s) with associated charts/datasets/databases.
         ---
         post:
+          summary: Import dashboard(s) with associated charts/datasets/databases
           requestBody:
             required: true
             content:
@@ -1211,12 +1204,10 @@ class DashboardRestApi(BaseSupersetModelRestApi):
     )
     @with_dashboard
     def get_embedded(self, dashboard: Dashboard) -> Response:
-        """Response
+        """Get the dashboard's embedded configuration.
-        Returns the dashboard's embedded configuration
         ---
         get:
-          description: >-
+          summary: Get the dashboard's embedded configuration
-            Returns the dashboard's embedded configuration
           parameters:
           - in: path
             schema:
@@ -1254,12 +1245,10 @@ class DashboardRestApi(BaseSupersetModelRestApi):
     )
     @with_dashboard
     def set_embedded(self, dashboard: Dashboard) -> Response:
-        """Response
+        """Set a dashboard's embedded configuration.
-        Sets a dashboard's embedded configuration.
         ---
         post:
-          description: >-
+          summary: Set a dashboard's embedded configuration
-            Sets a dashboard's embedded configuration.
           parameters:
           - in: path
             schema:
@@ -1335,12 +1324,10 @@ class DashboardRestApi(BaseSupersetModelRestApi):
     )
     @with_dashboard
     def delete_embedded(self, dashboard: Dashboard) -> Response:
-        """Response
+        """Delete a dashboard's embedded configuration.
-        Removes a dashboard's embedded configuration.
         ---
         delete:
-          description: >-
+          summary: Delete a dashboard's embedded configuration
-            Removes a dashboard's embedded configuration.
           parameters:
           - in: path
             schema:
@@ -1377,10 +1364,10 @@ class DashboardRestApi(BaseSupersetModelRestApi):
     )
     @with_dashboard
     def copy_dash(self, original_dash: Dashboard) -> Response:
-        """Makes a copy of an existing dashboard
+        """Create a copy of an existing dashboard.
         ---
         post:
-          summary: Makes a copy of an existing dashboard
+          summary: Create a copy of an existing dashboard
           parameters:
           - in: path
             schema:

superset/dashboards/filter_sets/api.py

@@ -131,12 +131,10 @@ class FilterSetRestApi(BaseSupersetModelRestApi):
     @permission_name("get")
     @rison(get_list_schema)
     def get_list(self, dashboard_id: int, **kwargs: Any) -> Response:
-        """
+        """Get a dashboard's list of filter sets.
-            Gets a dashboard's Filter sets
+        ---
-         ---
         get:
-          description: >-
+          summary: Get a dashboard's list of filter sets
-            Get a dashboard's list of filter sets
           parameters:
           - in: path
             schema:
@@ -198,12 +196,10 @@ class FilterSetRestApi(BaseSupersetModelRestApi):
     )
     @requires_json
     def post(self, dashboard_id: int) -> Response:
-        """
+        """Create a new dashboard's filter set.
-            Creates a new Dashboard's Filter Set
         ---
         post:
-          description: >-
+          summary: Create a new dashboard's filter set
-            Create a new Dashboard's Filter Set.
           parameters:
           - in: path
             schema:
@@ -265,11 +261,10 @@ class FilterSetRestApi(BaseSupersetModelRestApi):
     )
     @requires_json
     def put(self, dashboard_id: int, pk: int) -> Response:
-        """Changes a Dashboard's Filter set
+        """Update a dashboard's filter set.
         ---
         put:
-          description: >-
+          summary: Update a dashboard's filter set
-            Changes a Dashboard's Filter set.
           parameters:
           - in: path
             schema:
@@ -336,12 +331,10 @@ class FilterSetRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def delete(self, dashboard_id: int, pk: int) -> Response:
-        """
+        """Delete a dashboard's filter set.
-            Deletes a Dashboard's FilterSet
         ---
         delete:
-          description: >-
+          summary: Delete a dashboard's filter set
-            Deletes a Dashboard.
           parameters:
           - in: path
             schema:

superset/dashboards/filter_state/api.py

@@ -54,11 +54,10 @@ class DashboardFilterStateRestApi(TemporaryCacheRestApi):
         log_to_statsd=False,
     )
     def post(self, pk: int) -> Response:
-        """Stores a new value.
+        """Create a dashboard's filter state.
         ---
         post:
-          description: >-
+          summary: Create a dashboard's filter state
-            Stores a new value.
           parameters:
           - in: path
             schema:
@@ -104,11 +103,10 @@ class DashboardFilterStateRestApi(TemporaryCacheRestApi):
         log_to_statsd=False,
     )
     def put(self, pk: int, key: str) -> Response:
-        """Updates an existing value.
+        """Update a dashboard's filter state value.
         ---
         put:
-          description: >-
+          summary: Update a dashboard's filter state value
-            Updates an existing value.
           parameters:
           - in: path
             schema:
@@ -160,11 +158,10 @@ class DashboardFilterStateRestApi(TemporaryCacheRestApi):
         log_to_statsd=False,
     )
     def get(self, pk: int, key: str) -> Response:
-        """Retrives a value.
+        """Get a dashboard's filter state value.
         ---
         get:
-          description: >-
+          summary: Get a dashboard's filter state value
-            Retrives a value.
           parameters:
           - in: path
             schema:
@@ -206,11 +203,10 @@ class DashboardFilterStateRestApi(TemporaryCacheRestApi):
         log_to_statsd=False,
     )
     def delete(self, pk: int, key: str) -> Response:
-        """Deletes a value.
+        """Delete a dashboard's filter state value.
         ---
         delete:
-          description: >-
+          summary: Delete a dashboard's filter state value
-            Deletes a value.
           parameters:
           - in: path
             schema:

superset/dashboards/permalink/api.py

@@ -56,11 +56,10 @@ class DashboardPermalinkRestApi(BaseSupersetApi):
     )
     @requires_json
     def post(self, pk: str) -> Response:
-        """Stores a new permanent link.
+        """Create a new dashboard's permanent link.
         ---
         post:
-          description: >-
+          summary: Create a new dashboard's permanent link
-            Stores a new permanent link.
           parameters:
           - in: path
             schema:
@@ -122,11 +121,10 @@ class DashboardPermalinkRestApi(BaseSupersetApi):
         log_to_statsd=False,
     )
     def get(self, key: str) -> Response:
-        """Retrives permanent link state for dashboard.
+        """Get dashboard's permanent link state.
         ---
         get:
-          description: >-
+          summary: Get dashboard's permanent link state
-            Retrives dashboard state associated with a permanent link.
           parameters:
           - in: path
             schema:

superset/dashboards/schemas.py

@@ -69,20 +69,16 @@ certified_by_description = "Person or group that has certified this dashboard"
 certification_details_description = "Details of the certification"
 
 openapi_spec_methods_override = {
-    "get": {"get": {"description": "Get a dashboard detail information."}},
+    "get": {"get": {"summary": "Get a dashboard detail information"}},
     "get_list": {
         "get": {
-            "description": "Get a list of dashboards, use Rison or JSON query "
+            "summary": "Get a list of dashboards",
+            "description": "Gets a list of dashboards, use Rison or JSON query "
             "parameters for filtering, sorting, pagination and "
             " for selecting specific columns and metadata.",
         }
     },
-    "info": {
+    "info": {"get": {"summary": "Get metadata information about this API resource"}},
-        "get": {
-            "description": "Several metadata information about dashboard API "
-            "endpoints.",
-        }
-    },
     "related": {
         "get": {"description": "Get a list of all possible owners for a dashboard."}
     },

superset/databases/api.py

@@ -71,6 +71,7 @@ from superset.databases.schemas import (
     DatabaseTestConnectionSchema,
     DatabaseValidateParametersSchema,
     get_export_ids_schema,
+    openapi_spec_methods_override,
     SchemasResponseSchema,
     SelectStarResponseSchema,
     TableExtraMetadataResponseSchema,
@@ -234,6 +235,9 @@ class DatabaseRestApi(BaseSupersetModelRestApi):
         ValidateSQLResponse,
     )
 
+    openapi_spec_methods = openapi_spec_methods_override
+    """ Overrides GET methods OpenApi descriptions """
+
     @expose("/<int:pk>/connection", methods=("GET",))
     @protect()
     @safe
@@ -241,8 +245,7 @@ class DatabaseRestApi(BaseSupersetModelRestApi):
         """Get database connection info.
         ---
         get:
-          summary: >-
+          summary: Get a database connection info
-            Get a database connection info
           parameters:
           - in: path
             schema:
@@ -282,11 +285,10 @@ class DatabaseRestApi(BaseSupersetModelRestApi):
     @protect()
     @safe
     def get(self, pk: int, **kwargs: Any) -> Response:
-        """Get a database
+        """Get a database.
         ---
         get:
-          description: >-
+          summary: Get a database
-            Get a database
           parameters:
           - in: path
             schema:
@@ -329,11 +331,10 @@ class DatabaseRestApi(BaseSupersetModelRestApi):
     )
     @requires_json
     def post(self) -> FlaskResponse:
-        """Creates a new Database
+        """Create a new database.
         ---
         post:
-          description: >-
+          summary: Create a new database
-            Create a new Database.
           requestBody:
             description: Database schema
             required: true
@@ -415,11 +416,10 @@ class DatabaseRestApi(BaseSupersetModelRestApi):
     )
     @requires_json
     def put(self, pk: int) -> Response:
-        """Changes a Database
+        """Update a database.
         ---
         put:
-          description: >-
+          summary: Change a database
-            Changes a Database.
           parameters:
           - in: path
             schema:
@@ -498,11 +498,10 @@ class DatabaseRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def delete(self, pk: int) -> Response:
-        """Deletes a Database
+        """Delete a database.
         ---
         delete:
-          description: >-
+          summary: Delete a database
-            Deletes a Database.
           parameters:
           - in: path
             schema:
@@ -555,10 +554,10 @@ class DatabaseRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def schemas(self, pk: int, **kwargs: Any) -> FlaskResponse:
-        """Get all schemas from a database
+        """Get all schemas from a database.
         ---
         get:
-          description: Get all schemas from a database
+          summary: Get all schemas from a database
           parameters:
           - in: path
             schema:
@@ -615,7 +614,7 @@ class DatabaseRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def tables(self, pk: int, **kwargs: Any) -> FlaskResponse:
-        """Get a list of tables for given database
+        """Get a list of tables for given database.
         ---
         get:
           summary: Get a list of tables for given database
@@ -685,10 +684,10 @@ class DatabaseRestApi(BaseSupersetModelRestApi):
     def table_metadata(
         self, database: Database, table_name: str, schema_name: str
     ) -> FlaskResponse:
-        """Table schema info
+        """Get database table metadata.
         ---
         get:
-          description: Get database table metadata
+          summary: Get database table metadata
           parameters:
           - in: path
             schema:
@@ -748,13 +747,12 @@ class DatabaseRestApi(BaseSupersetModelRestApi):
     def table_extra_metadata(
         self, database: Database, table_name: str, schema_name: str
     ) -> FlaskResponse:
-        """Table schema info
+        """Get table extra metadata.
         ---
         get:
-          summary: >-
+          summary: Get table extra metadata
-            Get table extra metadata
           description: >-
-            Response depends on each DB engine spec normally focused on partitions
+            Response depends on each DB engine spec normally focused on partitions.
           parameters:
           - in: path
             schema:
@@ -811,10 +809,10 @@ class DatabaseRestApi(BaseSupersetModelRestApi):
     def select_star(
         self, database: Database, table_name: str, schema_name: Optional[str] = None
     ) -> FlaskResponse:
-        """Table schema info
+        """Get database select star for table.
         ---
         get:
-          description: Get database select star for table
+          summary: Get database select star for table
           parameters:
           - in: path
             schema:
@@ -870,11 +868,10 @@ class DatabaseRestApi(BaseSupersetModelRestApi):
     )
     @requires_json
     def test_connection(self) -> FlaskResponse:
-        """Tests a database connection
+        """Test a database connection.
         ---
         post:
-          description: >-
+          summary: Test a database connection
-            Tests a database connection
           requestBody:
             description: Database schema
             required: true
@@ -920,11 +917,10 @@ class DatabaseRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def related_objects(self, pk: int) -> Response:
-        """Get charts and dashboards count associated to a database
+        """Get charts and dashboards count associated to a database.
         ---
         get:
-          description:
+          summary: Get charts and dashboards count associated to a database
-            Get charts and dashboards count associated to a database
           parameters:
           - in: path
             name: pk
@@ -987,13 +983,12 @@ class DatabaseRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def validate_sql(self, pk: int) -> FlaskResponse:
-        """
+        """Validate that arbitrary SQL is acceptable for the given database.
         ---
         post:
-          summary: >-
+          summary: Validate arbitrary SQL
-            Validates that arbitrary sql is acceptable for the given database
           description: >-
-            Validates arbitrary SQL.
+            Validates that arbitrary SQL is acceptable for the given database.
           parameters:
           - in: path
             schema:
@@ -1049,10 +1044,10 @@ class DatabaseRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def export(self, **kwargs: Any) -> Response:
-        """Export database(s) with associated datasets
+        """Download database(s) and associated dataset(s) as a zip file.
         ---
         get:
-          description: Download database(s) and associated dataset(s) as a zip file
+          summary: Download database(s) and associated dataset(s) as a zip file
           parameters:
           - in: query
             name: q
@@ -1111,9 +1106,10 @@ class DatabaseRestApi(BaseSupersetModelRestApi):
     )
     @requires_form_data
     def import_(self) -> Response:
-        """Import database(s) with associated datasets
+        """Import database(s) with associated datasets.
         ---
         post:
+          summary: Import database(s) with associated datasets
           requestBody:
             required: true
             content:
@@ -1233,11 +1229,10 @@ class DatabaseRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def function_names(self, pk: int) -> Response:
-        """Get function names supported by a database
+        """Get function names supported by a database.
         ---
         get:
-          description:
+          summary: Get function names supported by a database
-            Get function names supported by a database
           parameters:
           - in: path
             name: pk
@@ -1273,11 +1268,10 @@ class DatabaseRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def available(self) -> Response:
-        """Return names of databases currently available
+        """Get names of databases currently available.
         ---
         get:
-          description:
+          summary: Get names of databases currently available
-            Get names of databases currently available
           responses:
             200:
               description: Database names
@@ -1386,11 +1380,10 @@ class DatabaseRestApi(BaseSupersetModelRestApi):
     )
     @requires_json
     def validate_parameters(self) -> FlaskResponse:
-        """validates database connection parameters
+        """Validate database connection parameters.
         ---
         post:
-          description: >-
+          summary: Validate database connection parameters
-            Validates parameters used to connect to a database
           requestBody:
             description: DB-specific parameters
             required: true
@@ -1442,11 +1435,10 @@ class DatabaseRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def delete_ssh_tunnel(self, pk: int) -> Response:
-        """Deletes a SSH Tunnel
+        """Delete a SSH tunnel.
         ---
         delete:
-          description: >-
+          summary: Delete a SSH tunnel
-            Deletes a SSH Tunnel.
           parameters:
           - in: path
             schema:
@@ -1505,11 +1497,10 @@ class DatabaseRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def schemas_access_for_file_upload(self, pk: int) -> Response:
-        """The list of the database schemas where to upload information
+        """The list of the database schemas where to upload information.
         ---
         get:
-          summary:
+          summary: The list of the database schemas where to upload information
-            The list of the database schemas where to upload information
           parameters:
           - in: path
             name: pk

superset/databases/schemas.py

@@ -150,6 +150,18 @@ server_cert_description = markdown(
     True,
 )
 
+openapi_spec_methods_override = {
+    "get_list": {
+        "get": {
+            "summary": "Get a list of databases",
+            "description": "Gets a list of databases, use Rison or JSON query "
+            "parameters for filtering, sorting, pagination and "
+            " for selecting specific columns and metadata.",
+        }
+    },
+    "info": {"get": {"summary": "Get metadata information about this API resource"}},
+}
+
 
 def sqlalchemy_uri_validator(value: str) -> str:
     """

superset/datasets/api.py

@@ -65,6 +65,7 @@ from superset.datasets.schemas import (
     get_delete_ids_schema,
     get_export_ids_schema,
     GetOrCreateDatasetSchema,
+    openapi_spec_methods_override,
 )
 from superset.utils.core import parse_boolean_string
 from superset.views.base import DatasourceFilter, generate_download_headers
@@ -257,6 +258,9 @@ class DatasetRestApi(BaseSupersetModelRestApi):
         GetOrCreateDatasetSchema,
     )
 
+    openapi_spec_methods = openapi_spec_methods_override
+    """ Overrides GET methods OpenApi descriptions """
+
     list_outer_default_load = True
     show_outer_default_load = True
 
@@ -270,11 +274,10 @@ class DatasetRestApi(BaseSupersetModelRestApi):
     )
     @requires_json
     def post(self) -> Response:
-        """Creates a new Dataset
+        """Create a new dataset.
         ---
         post:
-          description: >-
+          summary: Create a new dataset
-            Create a new Dataset
           requestBody:
             description: Dataset schema
             required: true
@@ -333,11 +336,10 @@ class DatasetRestApi(BaseSupersetModelRestApi):
     )
     @requires_json
     def put(self, pk: int) -> Response:
-        """Changes a Dataset
+        """Update a dataset.
         ---
         put:
-          description: >-
+          summary: Update a dataset
-            Changes a Dataset
           parameters:
           - in: path
             schema:
@@ -419,11 +421,10 @@ class DatasetRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def delete(self, pk: int) -> Response:
-        """Deletes a Dataset
+        """Delete a Dataset.
         ---
         delete:
-          description: >-
+          summary: Delete a dataset
-            Deletes a Dataset
           parameters:
           - in: path
             schema:
@@ -476,11 +477,10 @@ class DatasetRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def export(self, **kwargs: Any) -> Response:  # pylint: disable=too-many-locals
-        """Export datasets
+        """Download multiple datasets as YAML files.
         ---
         get:
-          description: >-
+          summary: Download multiple datasets as YAML files
-            Exports multiple datasets and downloads them as YAML files
           parameters:
           - in: query
             name: q
@@ -560,11 +560,10 @@ class DatasetRestApi(BaseSupersetModelRestApi):
     )
     @requires_json
     def duplicate(self) -> Response:
-        """Duplicates a Dataset
+        """Duplicate a dataset.
         ---
         post:
-          description: >-
+          summary: Duplicate a dataset
-            Duplicates a Dataset
           requestBody:
             description: Dataset schema
             required: true
@@ -630,11 +629,10 @@ class DatasetRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def refresh(self, pk: int) -> Response:
-        """Refresh a Dataset
+        """Refresh and update columns of a dataset.
         ---
         put:
-          description: >-
+          summary: Refresh and update columns of a dataset
-            Refreshes and updates columns of a dataset
           parameters:
           - in: path
             schema:
@@ -687,11 +685,10 @@ class DatasetRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def related_objects(self, pk: int) -> Response:
-        """Get charts and dashboards count associated to a dataset
+        """Get charts and dashboards count associated to a dataset.
         ---
         get:
-          description:
+          summary: Get charts and dashboards count associated to a dataset
-            Get charts and dashboards count associated to a dataset
           parameters:
           - in: path
             name: pk
@@ -749,11 +746,10 @@ class DatasetRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def bulk_delete(self, **kwargs: Any) -> Response:
-        """Delete bulk Datasets
+        """Bulk delete datasets.
         ---
         delete:
-          description: >-
+          summary: Bulk delete datasets
-            Deletes multiple Datasets in a bulk operation.
           parameters:
           - in: query
             name: q
@@ -811,9 +807,10 @@ class DatasetRestApi(BaseSupersetModelRestApi):
     )
     @requires_form_data
     def import_(self) -> Response:
-        """Import dataset(s) with associated databases
+        """Import dataset(s) with associated databases.
         ---
         post:
+          summary: Import dataset(s) with associated databases
           requestBody:
             required: true
             content:
@@ -945,7 +942,7 @@ class DatasetRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def get_or_create_dataset(self) -> Response:
-        """Retrieve a dataset by name, or create it if it does not exist
+        """Retrieve a dataset by name, or create it if it does not exist.
         ---
         post:
           summary: Retrieve a table by name, or create it if it does not exist
@@ -1011,11 +1008,10 @@ class DatasetRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def warm_up_cache(self) -> Response:
-        """
+        """Warm up the cache for each chart powered by the given table.
         ---
         put:
-          summary: >-
+          summary: Warm up the cache for each chart powered by the given table
-            Warms up the cache for each chart powered by the given table
           description: >-
             Warms up the cache for the table.
             Note for slices a force refresh occurs.

superset/datasets/columns/api.py

@@ -53,11 +53,10 @@ class DatasetColumnsRestApi(BaseSupersetModelRestApi):
     def delete(  # pylint: disable=arguments-differ
         self, pk: int, column_id: int
     ) -> Response:
-        """Deletes a Dataset column
+        """Delete a dataset column.
         ---
         delete:
-          description: >-
+          summary: Delete a dataset column
-            Delete a Dataset column
           parameters:
           - in: path
             schema:

superset/datasets/metrics/api.py

@@ -53,11 +53,10 @@ class DatasetMetricRestApi(BaseSupersetModelRestApi):
     def delete(  # pylint: disable=arguments-differ
         self, pk: int, metric_id: int
     ) -> Response:
-        """Deletes a Dataset metric
+        """Delete a dataset metric.
         ---
         delete:
-          description: >-
+          summary: Delete a dataset metric
-            Delete a Dataset metric
           parameters:
           - in: path
             schema:

superset/datasets/schemas.py

@@ -28,6 +28,19 @@ from superset.datasets.models import Dataset
 get_delete_ids_schema = {"type": "array", "items": {"type": "integer"}}
 get_export_ids_schema = {"type": "array", "items": {"type": "integer"}}
 
+openapi_spec_methods_override = {
+    "get": {"get": {"summary": "Get a dataset detail information"}},
+    "get_list": {
+        "get": {
+            "summary": "Get a list of datasets",
+            "description": "Gets a list of datasets, use Rison or JSON query "
+            "parameters for filtering, sorting, pagination and "
+            " for selecting specific columns and metadata.",
+        }
+    },
+    "info": {"get": {"summary": "Get metadata information about this API resource"}},
+}
+
 
 def validate_python_date_format(value: str) -> None:
     regex = re.compile(

superset/datasource/api.py

@@ -50,7 +50,7 @@ class DatasourceRestApi(BaseSupersetApi):
     def get_column_values(
         self, datasource_type: str, datasource_id: int, column_name: str
     ) -> FlaskResponse:
-        """Get possible values for a datasource column
+        """Get possible values for a datasource column.
         ---
         get:
           summary: Get possible values for a datasource column

superset/embedded/api.py

@@ -68,12 +68,10 @@ class EmbeddedDashboardRestApi(BaseSupersetModelRestApi):
     )
     # pylint: disable=arguments-differ, arguments-renamed)
     def get(self, uuid: str) -> Response:
-        """Response
+        """Get the dashboard's embedded configuration.
-        Returns the dashboard's embedded configuration
         ---
         get:
-          description: >-
+          summary: Get the dashboard's embedded configuration
-            Returns the dashboard's embedded configuration
           parameters:
           - in: path
             schema:

superset/explore/api.py

@@ -53,16 +53,14 @@ class ExploreRestApi(BaseSupersetApi):
         log_to_statsd=True,
     )
     def get(self) -> Response:
-        """Assembles Explore related information (form_data, slice, dataset)
+        """Assemble Explore related information (form_data, slice, dataset)
-         in a single endpoint.
+        in a single endpoint.
         ---
         get:
-          summary: >-
+          summary: Assemble Explore related information in a single endpoint
-            Assembles Explore related information (form_data, slice, dataset)
-             in a single endpoint.
           description: >-
-            Assembles Explore related information (form_data, slice, dataset)
+            Assembles Explore related information (form_data, slice, dataset) in a
-             in a single endpoint.<br/><br/>
+            single endpoint.<br/><br/>
             The information can be assembled from:<br/>
             - The cache using a form_data_key<br/>
             - The metadata database using a permalink_key<br/>

superset/explore/form_data/api.py

@@ -57,11 +57,10 @@ class ExploreFormDataRestApi(BaseSupersetApi):
     )
     @requires_json
     def post(self) -> Response:
-        """Stores a new form_data.
+        """Create a new form_data.
         ---
         post:
-          description: >-
+          summary: Create a new form_data
-            Stores a new form_data.
           parameters:
           - in: query
             schema:
@@ -122,11 +121,10 @@ class ExploreFormDataRestApi(BaseSupersetApi):
     )
     @requires_json
     def put(self, key: str) -> Response:
-        """Updates an existing form_data.
+        """Update an existing form_data.
         ---
         put:
-          description: >-
+          summary: Update an existing form_data
-            Updates an existing form_data.
           parameters:
           - in: path
             schema:
@@ -195,11 +193,10 @@ class ExploreFormDataRestApi(BaseSupersetApi):
         log_to_statsd=True,
     )
     def get(self, key: str) -> Response:
-        """Retrives a form_data.
+        """Get a form_data.
         ---
         get:
-          description: >-
+          summary: Get a form_data
-            Retrives a form_data.
           parameters:
           - in: path
             schema:
@@ -247,11 +244,10 @@ class ExploreFormDataRestApi(BaseSupersetApi):
         log_to_statsd=True,
     )
     def delete(self, key: str) -> Response:
-        """Deletes a form_data.
+        """Delete a form_data.
         ---
         delete:
-          description: >-
+          summary: Delete a form_data
-            Deletes a form_data.
           parameters:
           - in: path
             schema:

superset/explore/permalink/api.py

@@ -59,11 +59,10 @@ class ExplorePermalinkRestApi(BaseSupersetApi):
     )
     @requires_json
     def post(self) -> Response:
-        """Stores a new permanent link.
+        """Create a new permanent link.
         ---
         post:
-          description: >-
+          summary: Create a new permanent link
-            Stores a new permanent link.
           requestBody:
             required: true
             content:
@@ -119,11 +118,10 @@ class ExplorePermalinkRestApi(BaseSupersetApi):
         log_to_statsd=False,
     )
     def get(self, key: str) -> Response:
-        """Retrives permanent link state for chart.
+        """Get chart's permanent link state.
         ---
         get:
-          description: >-
+          summary: Get chart's permanent link state
-            Retrives chart state associated with a permanent link.
           parameters:
           - in: path
             schema:

superset/importexport/api.py

@@ -50,12 +50,12 @@ class ImportExportRestApi(BaseSupersetApi):
         log_to_statsd=False,
     )
     def export(self) -> Response:
-        """
+        """Export all assets.
-        Export all assets.
         ---
         get:
+          summary: Export all assets
           description: >-
-            Returns a ZIP file with all the Superset assets (databases, datasets, charts,
+            Gets a ZIP file with all the Superset assets (databases, datasets, charts,
             dashboards, saved queries) as YAML files.
           responses:
             200:
@@ -100,9 +100,10 @@ class ImportExportRestApi(BaseSupersetApi):
     )
     @requires_form_data
     def import_(self) -> Response:
-        """Import multiple assets
+        """Import multiple assets.
         ---
         post:
+          summary: Import multiple assets
           requestBody:
             required: true
             content:

superset/queries/api.py

@@ -159,7 +159,7 @@ class QueryRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def get_updated_since(self, **kwargs: Any) -> FlaskResponse:
-        """Get a list of queries that changed after last_updated_ms
+        """Get a list of queries that changed after last_updated_ms.
         ---
         get:
           summary: Get a list of queries that changed after last_updated_ms
@@ -220,7 +220,7 @@ class QueryRestApi(BaseSupersetModelRestApi):
     )
     @requires_json
     def stop_query(self) -> FlaskResponse:
-        """Manually stop a query with client_id
+        """Manually stop a query with client_id.
         ---
         post:
           summary: Manually stop a query with client_id

superset/queries/saved_queries/api.py

@@ -178,11 +178,10 @@ class SavedQueryRestApi(BaseSupersetModelRestApi):
     @statsd_metrics
     @rison(get_delete_ids_schema)
     def bulk_delete(self, **kwargs: Any) -> Response:
-        """Delete bulk Saved Queries
+        """Bulk delete saved queries.
         ---
         delete:
-          description: >-
+          summary: Bulk delete saved queries
-            Deletes multiple saved queries in a bulk operation.
           parameters:
           - in: query
             name: q
@@ -231,11 +230,10 @@ class SavedQueryRestApi(BaseSupersetModelRestApi):
     @statsd_metrics
     @rison(get_export_ids_schema)
     def export(self, **kwargs: Any) -> Response:
-        """Export saved queries
+        """Download multiple saved queries as YAML files.
         ---
         get:
-          description: >-
+          summary: Download multiple saved queries as YAML files
-            Exports multiple saved queries and downloads them as YAML files
           parameters:
           - in: query
             name: q
@@ -296,9 +294,10 @@ class SavedQueryRestApi(BaseSupersetModelRestApi):
     )
     @requires_form_data
     def import_(self) -> Response:
-        """Import Saved Queries with associated databases
+        """Import saved queries with associated databases.
         ---
         post:
+          summary: Import saved queries with associated databases
           requestBody:
             required: true
             content:

superset/queries/saved_queries/schemas.py

@@ -18,22 +18,20 @@ from marshmallow import fields, Schema
 from marshmallow.validate import Length
 
 openapi_spec_methods_override = {
-    "get": {
+    "get": {"get": {"summary": "Get a saved query"}},
-        "get": {
-            "description": "Get a saved query",
-        }
-    },
     "get_list": {
         "get": {
-            "description": "Get a list of saved queries, use Rison or JSON "
+            "summary": "Get a list of saved queries",
+            "description": "Gets a list of saved queries, use Rison or JSON "
             "query parameters for filtering, sorting,"
             " pagination and for selecting specific"
             " columns and metadata.",
         }
     },
-    "post": {"post": {"description": "Create a saved query"}},
+    "post": {"post": {"summary": "Create a saved query"}},
-    "put": {"put": {"description": "Update a saved query"}},
+    "put": {"put": {"summary": "Update a saved query"}},
-    "delete": {"delete": {"description": "Delete saved query"}},
+    "delete": {"delete": {"summary": "Delete a saved query"}},
+    "info": {"get": {"summary": "Get metadata information about this API resource"}},
 }
 
 get_delete_ids_schema = {"type": "array", "items": {"type": "integer"}}

superset/queries/schemas.py

@@ -22,10 +22,11 @@ from superset.models.sql_lab import Query
 from superset.sql_parse import Table
 
 openapi_spec_methods_override = {
-    "get": {"get": {"description": "Get query detail information."}},
+    "get": {"get": {"summary": "Get query detail information"}},
     "get_list": {
         "get": {
-            "description": "Get a list of queries, use Rison or JSON query "
+            "summary": "Get a list of queries",
+            "description": "Gets a list of queries, use Rison or JSON query "
             "parameters for filtering, sorting, pagination and "
             " for selecting specific columns and metadata.",
         }

superset/reports/api.py

@@ -245,11 +245,10 @@ class ReportScheduleRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def delete(self, pk: int) -> Response:
-        """Delete a Report Schedule
+        """Delete a report schedule.
         ---
         delete:
-          description: >-
+          summary: Delete a report schedule
-            Delete a Report Schedule
           parameters:
           - in: path
             schema:
@@ -299,11 +298,10 @@ class ReportScheduleRestApi(BaseSupersetModelRestApi):
     def post(
         self,
     ) -> Response:
-        """Creates a new Report Schedule
+        """Create a new report schedule.
         ---
         post:
-          description: >-
+          summary: Create a new report schedule
-            Create a new Report Schedule
           requestBody:
             description: Report Schedule schema
             required: true
@@ -372,11 +370,10 @@ class ReportScheduleRestApi(BaseSupersetModelRestApi):
     @permission_name("put")
     @requires_json
     def put(self, pk: int) -> Response:
-        """Updates an Report Schedule
+        """Update a report schedule.
         ---
         put:
-          description: >-
+          summary: Update a report schedule
-            Updates a Report Schedule
           parameters:
           - in: path
             schema:
@@ -458,11 +455,10 @@ class ReportScheduleRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def bulk_delete(self, **kwargs: Any) -> Response:
-        """Delete bulk Report Schedule layers
+        """Bulk delete report schedules.
         ---
         delete:
-          description: >-
+          summary: Bulk delete report schedules
-            Deletes multiple report schedules in a bulk operation.
           parameters:
           - in: query
             name: q

superset/reports/logs/api.py

@@ -99,11 +99,10 @@ class ReportExecutionLogRestApi(BaseSupersetModelRestApi):
     def get_list(  # pylint: disable=arguments-differ
         self, pk: int, **kwargs: Any
     ) -> Response:
-        """Get a list of report schedule logs
+        """Get a list of report schedule logs.
         ---
         get:
-          description: >-
+          summary: Get a list of report schedule logs
-            Get a list of report schedule logs
           parameters:
           - in: path
             schema:
@@ -160,11 +159,10 @@ class ReportExecutionLogRestApi(BaseSupersetModelRestApi):
     def get(  # pylint: disable=arguments-differ
         self, pk: int, log_id: int, **kwargs: Any
     ) -> Response:
-        """Get a report schedule log
+        """Get a report schedule log.
         ---
         get:
-          description: >-
+          summary: Get a report schedule log
-            Get a report schedule log
           parameters:
           - in: path
             schema:

superset/reports/logs/schemas.py

@@ -16,10 +16,11 @@
 # under the License.
 
 openapi_spec_methods_override = {
-    "get": {"get": {"description": "Get a report schedule log"}},
+    "get": {"get": {"summary": "Get a report schedule log"}},
     "get_list": {
         "get": {
-            "description": "Get a list of report schedule logs, use Rison or JSON "
+            "summary": "Get a list of report schedule logs",
+            "description": "Gets a list of report schedule logs, use Rison or JSON "
             "query parameters for filtering, sorting,"
             " pagination and for selecting specific"
             " columns and metadata.",

superset/reports/schemas.py

@@ -32,18 +32,20 @@ from superset.reports.models import (
 )
 
 openapi_spec_methods_override = {
-    "get": {"get": {"description": "Get a report schedule"}},
+    "get": {"get": {"summary": "Get a report schedule"}},
     "get_list": {
         "get": {
-            "description": "Get a list of report schedules, use Rison or JSON "
+            "summary": "Get a list of report schedules",
+            "description": "Gets a list of report schedules, use Rison or JSON "
             "query parameters for filtering, sorting,"
             " pagination and for selecting specific"
             " columns and metadata.",
         }
     },
-    "post": {"post": {"description": "Create a report schedule"}},
+    "post": {"post": {"summary": "Create a report schedule"}},
-    "put": {"put": {"description": "Update a report schedule"}},
+    "put": {"put": {"summary": "Update a report schedule"}},
-    "delete": {"delete": {"description": "Delete a report schedule"}},
+    "delete": {"delete": {"summary": "Delete a report schedule"}},
+    "info": {"get": {"summary": "Get metadata information about this API resource"}},
 }
 
 get_delete_ids_schema = {"type": "array", "items": {"type": "integer"}}

superset/row_level_security/api.py

@@ -38,6 +38,7 @@ from superset.row_level_security.commands.exceptions import RLSRuleNotFoundError
 from superset.row_level_security.commands.update import UpdateRLSRuleCommand
 from superset.row_level_security.schemas import (
     get_delete_ids_schema,
+    openapi_spec_methods_override,
     RLSListSchema,
     RLSPostSchema,
     RLSPutSchema,
@@ -128,6 +129,9 @@ class RLSRestApi(BaseSupersetModelRestApi):
         "roles": [["id", BaseFilterRelatedRoles, lambda: []]],
     }
 
+    openapi_spec_methods = openapi_spec_methods_override
+    """ Overrides GET methods OpenApi descriptions """
+
     @expose("/", methods=("POST",))
     @protect()
     @safe
@@ -138,11 +142,10 @@ class RLSRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def post(self) -> Response:
-        """Creates a new RLS rule
+        """Create a new RLS rule.
         ---
         post:
-          description: >-
+          summary: Create a new RLS rule
-            Create a new RLS Rule
           requestBody:
             description: RLS schema
             required: true
@@ -216,11 +219,10 @@ class RLSRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def put(self, pk: int) -> Response:
-        """Updates an RLS Rule
+        """Update an RLS rule.
         ---
         put:
-          description: >-
+          summary: Update an RLS rule
-            Updates an RLS Rule
           parameters:
           - in: path
             schema:
@@ -305,11 +307,10 @@ class RLSRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def bulk_delete(self, **kwargs: Any) -> Response:
-        """Delete bulk RLS rules
+        """Bulk delete RLS rules.
         ---
         delete:
-          description: >-
+          summary: Bulk delete RLS rules
-            Deletes multiple RLS rules in a bulk operation.
           parameters:
           - in: query
             name: q

superset/row_level_security/schemas.py

@@ -37,6 +37,21 @@ clause_description = "This is the condition that will be added to the WHERE clau
 
 get_delete_ids_schema = {"type": "array", "items": {"type": "integer"}}
 
+openapi_spec_methods_override = {
+    "get": {"get": {"summary": "Get an RLS"}},
+    "get_list": {
+        "get": {
+            "summary": "Get a list of RLS",
+            "description": "Gets a list of RLS, use Rison or JSON "
+            "query parameters for filtering, sorting,"
+            " pagination and for selecting specific"
+            " columns and metadata.",
+        }
+    },
+    "delete": {"delete": {"summary": "Delete an RLS"}},
+    "info": {"get": {"summary": "Get metadata information about this API resource"}},
+}
+
 
 class RolesSchema(Schema):
     name = fields.String()

superset/security/api.py

@@ -88,12 +88,10 @@ class SecurityRestApi(BaseSupersetApi):
     @statsd_metrics
     @permission_name("read")
     def csrf_token(self) -> Response:
-        """
+        """Get the CSRF token.
-        Return the csrf token
         ---
         get:
-          description: >-
+          summary: Get the CSRF token
-            Fetch the CSRF token
           responses:
             200:
               description: Result contains the CSRF token
@@ -118,12 +116,10 @@ class SecurityRestApi(BaseSupersetApi):
     @statsd_metrics
     @permission_name("grant_guest_token")
     def guest_token(self) -> Response:
-        """Response
+        """Get a guest token that can be used for auth in embedded Superset.
-        Returns a guest token that can be used for auth in embedded Superset
         ---
         post:
-          description: >-
+          summary: Get a guest token
-            Fetches a guest token
           requestBody:
             description: Parameters for the guest token
             required: true

superset/sqllab/api.py

@@ -95,11 +95,10 @@ class SqlLabRestApi(BaseSupersetApi):
         log_to_statsd=False,
     )
     def estimate_query_cost(self) -> Response:
-        """Estimates the SQL query execution cost
+        """Estimate the SQL query execution cost.
         ---
         post:
-          summary: >-
+          summary: Estimate the SQL query execution cost
-            Estimates the SQL query execution cost
           requestBody:
             description: SQL query and params
             required: true
@@ -144,11 +143,10 @@ class SqlLabRestApi(BaseSupersetApi):
         log_to_statsd=False,
     )
     def export_csv(self, client_id: str) -> CsvResponse:
-        """Exports the SQL query results to a CSV
+        """Export the SQL query results to a CSV.
         ---
         get:
-          summary: >-
+          summary: Export the SQL query results to a CSV
-            Exports the SQL query results to a CSV
           parameters:
           - in: path
             schema:
@@ -206,11 +204,10 @@ class SqlLabRestApi(BaseSupersetApi):
         log_to_statsd=False,
     )
     def get_results(self, **kwargs: Any) -> FlaskResponse:
-        """Gets the result of a SQL query execution
+        """Get the result of a SQL query execution.
         ---
         get:
-          summary: >-
+          summary: Get the result of a SQL query execution
-            Gets the result of a SQL query execution
           parameters:
           - in: query
             name: q
@@ -260,11 +257,10 @@ class SqlLabRestApi(BaseSupersetApi):
         log_to_statsd=False,
     )
     def execute_sql_query(self) -> FlaskResponse:
-        """Executes a SQL query
+        """Execute a SQL query.
         ---
         post:
-          description: >-
+          summary: Execute a SQL query
-            Starts the execution of a SQL query
           requestBody:
             description: SQL query and params
             required: true

superset/tags/api.py

@@ -140,11 +140,12 @@ class TagRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def add_objects(self, object_type: ObjectTypes, object_id: int) -> Response:
-        """Adds tags to an object. Creates new tags if they do not already exist
+        """Add tags to an object. Create new tags if they do not already exist.
         ---
         post:
+          summary: Add tags to an object
           description: >-
-            Add tags to an object..
+            Adds tags to an object. Creates new tags if they do not already exist.
           requestBody:
             description: Tag schema
             required: true
@@ -213,11 +214,10 @@ class TagRestApi(BaseSupersetModelRestApi):
     def delete_object(
         self, object_type: ObjectTypes, object_id: int, tag: str
     ) -> Response:
-        """Deletes a Tagged Object
+        """Delete a tagged object.
         ---
         delete:
-          description: >-
+          summary: Delete a tagged object
-            Deletes a Tagged Object.
           parameters:
           - in: path
             schema:
@@ -280,11 +280,12 @@ class TagRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def bulk_delete(self, **kwargs: Any) -> Response:
-        """Delete Tags
+        """Bulk delete tags. This will remove all tagged objects with this tag.
         ---
         delete:
+          summary: Bulk delete tags
           description: >-
-            Deletes multiple Tags. This will remove all tagged objects with this tag
+            Bulk deletes tags. This will remove all tagged objects with this tag.
           parameters:
           - in: query
             name: q
@@ -334,11 +335,10 @@ class TagRestApi(BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def get_objects(self) -> Response:
-        """Gets all objects associated with a Tag
+        """Get all objects associated with a tag.
         ---
         get:
-          description: >-
+          summary: Get all objects associated with a tag
-            Gets all objects associated with a Tag.
           parameters:
           - in: path
             schema:

superset/tags/schemas.py

@@ -19,23 +19,22 @@ from marshmallow import fields, Schema
 from superset.dashboards.schemas import UserSchema
 
 delete_tags_schema = {"type": "array", "items": {"type": "string"}}
-
 object_type_description = "A title for the tag."
 
 openapi_spec_methods_override = {
-    "get": {"get": {"description": "Get a tag detail information."}},
+    "get": {"get": {"summary": "Get a tag detail information"}},
     "get_list": {
         "get": {
+            "summary": "Get a list of tags",
             "description": "Get a list of tags, use Rison or JSON query "
             "parameters for filtering, sorting, pagination and "
             " for selecting specific columns and metadata.",
         }
     },
-    "info": {
+    "put": {"put": {"summary": "Update a tag"}},
-        "get": {
+    "delete": {"delete": {"summary": "Delete a tag"}},
-            "description": "Several metadata information about tag API " "endpoints.",
+    "post": {"post": {"summary": "Create a tag"}},
-        }
+    "info": {"get": {"summary": "Get metadata information about tag API endpoints"}},
-    },
 }
 
 

superset/views/api.py

@@ -53,7 +53,7 @@ class Api(BaseSupersetView):
     @expose("/v1/query/", methods=("POST",))
     def query(self) -> FlaskResponse:
         """
-        Takes a query_obj constructed in the client and returns payload data response
+        Take a query_obj constructed in the client and returns payload data response
         for the given query_obj.
 
         raises SupersetSecurityException: If the user cannot access the resource
@@ -75,7 +75,7 @@ class Api(BaseSupersetView):
     @expose("/v1/form_data/", methods=("GET",))
     def query_form_data(self) -> FlaskResponse:
         """
-        Get the formdata stored in the database for existing slice.
+        Get the form_data stored in the database for existing slice.
         params: slice_id: integer
         """
         form_data = {}
@@ -94,7 +94,7 @@ class Api(BaseSupersetView):
     @rison(get_time_range_schema)
     @expose("/v1/time_range/", methods=("GET",))
     def time_range(self, **kwargs: Any) -> FlaskResponse:
-        """Get actually time range from human readable string or datetime expression"""
+        """Get actually time range from human-readable string or datetime expression."""
         time_range = kwargs["rison"]
         try:
             since, until = get_since_until(time_range)

superset/views/base_api.py

@@ -537,9 +537,10 @@ class BaseSupersetModelRestApi(ModelRestApi, BaseSupersetApiMixin):
     @rison(get_related_schema)
     @handle_api_exception
     def related(self, column_name: str, **kwargs: Any) -> FlaskResponse:
-        """Get related fields data
+        """Get related fields data.
         ---
         get:
+          summary: Get related fields data
           parameters:
           - in: path
             schema:
@@ -615,9 +616,10 @@ class BaseSupersetModelRestApi(ModelRestApi, BaseSupersetApiMixin):
     @rison(get_related_schema)
     @handle_api_exception
     def distinct(self, column_name: str, **kwargs: Any) -> FlaskResponse:
-        """Get distinct values from field data
+        """Get distinct values from field data.
         ---
         get:
+          summary: Get distinct values from field data
           parameters:
           - in: path
             schema:

superset/views/log/api.py

@@ -31,6 +31,7 @@ from superset.views.base_api import BaseSupersetModelRestApi, statsd_metrics
 from superset.views.log import LogMixin
 from superset.views.log.schemas import (
     get_recent_activity_schema,
+    openapi_spec_methods_override,
     RecentActivityResponseSchema,
     RecentActivitySchema,
 )
@@ -64,6 +65,9 @@ class LogRestApi(LogMixin, BaseSupersetModelRestApi):
         RecentActivitySchema,
     )
 
+    openapi_spec_methods = openapi_spec_methods_override
+    """ Overrides GET methods OpenApi descriptions """
+
     @staticmethod
     def is_enabled() -> bool:
         return app.config["FAB_ADD_SECURITY_VIEWS"] and app.config["SUPERSET_LOG_VIEW"]
@@ -92,7 +96,7 @@ class LogRestApi(LogMixin, BaseSupersetModelRestApi):
         log_to_statsd=False,
     )
     def recent_activity(self, **kwargs: Any) -> FlaskResponse:
-        """Get recent activity data for a user
+        """Get recent activity data for a user.
         ---
         get:
           summary: Get recent activity data for a user

superset/views/log/schemas.py

@@ -26,6 +26,18 @@ get_recent_activity_schema = {
     },
 }
 
+openapi_spec_methods_override = {
+    "get": {"get": {"summary": "Get a log detail information"}},
+    "get_list": {
+        "get": {
+            "summary": "Get a list of logs",
+            "description": "Gets a list of logs, use Rison or JSON query "
+            "parameters for filtering, sorting, pagination and "
+            " for selecting specific columns and metadata.",
+        }
+    },
+}
+
 
 class RecentActivitySchema(Schema):
     action = fields.String(

superset/views/users/api.py

@@ -26,7 +26,7 @@ user_response_schema = UserResponseSchema()
 
 
 class CurrentUserRestApi(BaseSupersetApi):
-    """An api to get information about the current user"""
+    """An API to get information about the current user"""
 
     resource_name = "me"
     openapi_spec_tag = "Current User"
@@ -35,11 +35,12 @@ class CurrentUserRestApi(BaseSupersetApi):
     @expose("/", methods=("GET",))
     @safe
     def get_me(self) -> Response:
-        """Get the user object corresponding to the agent making the request
+        """Get the user object corresponding to the agent making the request.
         ---
         get:
+          summary: Get the user object
           description: >-
-            Returns the user object corresponding to the agent making the request,
+            Gets the user object corresponding to the agent making the request,
             or returns a 401 error if the user is unauthenticated.
           responses:
             200:
@@ -65,11 +66,12 @@ class CurrentUserRestApi(BaseSupersetApi):
     @expose("/roles/", methods=("GET",))
     @safe
     def get_my_roles(self) -> Response:
-        """Get the user roles corresponding to the agent making the request
+        """Get the user roles corresponding to the agent making the request.
         ---
         get:
+          summary: Get the user roles
           description: >-
-            Returns the user roles corresponding to the agent making the request,
+            Gets the user roles corresponding to the agent making the request,
             or returns a 401 error if the user is unauthenticated.
           responses:
             200: