diff --git a/superset/advanced_data_type/api.py b/superset/advanced_data_type/api.py index a619a2a27e338..e0d4b9368bf32 100644 --- 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 index 484335b81cc3e..4c95b3c105a1f 100644 --- 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 index 79ea66aad0b58..7aa553d2a16bb 100644 --- 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 index 2e64fec78c95a..b7a3b301bc952 100644 --- 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 index 17c3c274cd173..1992d423fc482 100644 --- 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 index e1b49a72c06c1..8b682c396a882 100644 --- 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 index 5b422e6303228..0b8253d942fe5 100644 --- 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 index cb9b676287a15..9efc3d4c7a27e 100644 --- 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 diff --git a/superset/charts/api.py b/superset/charts/api.py index a060b23b0efbc..768d3302915c2 100644 --- a/superset/charts/api.py +++ b/superset/charts/api.py @@ -285,11 +285,10 @@ def ensure_thumbnails_enabled(self) -> Optional[Response]: ) @requires_json def post(self) -> Response: - """Creates a new Chart + """Create a new chart. --- post: - description: >- - Create a new Chart. + summary: Create a new chart requestBody: description: Chart schema required: true @@ -351,11 +350,10 @@ def post(self) -> Response: ) @requires_json def put(self, pk: int) -> Response: - """Changes a Chart + """Update a chart. --- put: - description: >- - Changes a Chart. + summary: Update a chart parameters: - in: path schema: @@ -427,11 +425,10 @@ def put(self, pk: int) -> Response: log_to_statsd=False, ) def delete(self, pk: int) -> Response: - """Deletes a Chart + """Delete a chart. --- delete: - description: >- - Deletes a Chart. + summary: Delete a chart parameters: - in: path schema: @@ -484,11 +481,10 @@ def delete(self, pk: int) -> Response: log_to_statsd=False, ) def bulk_delete(self, **kwargs: Any) -> Response: - """Delete bulk Charts + """Bulk delete charts. --- delete: - description: >- - Deletes multiple Charts in a bulk operation. + summary: Bulk delete charts parameters: - in: query name: q @@ -544,10 +540,10 @@ def bulk_delete(self, **kwargs: Any) -> Response: 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 @@ def trigger_celery() -> WerkzeugResponse: 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 @@ def screenshot(self, pk: int, digest: str) -> WerkzeugResponse: 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 @@ def thumbnail(self, pk: int, digest: str, **kwargs: Any) -> WerkzeugResponse: log_to_statsd=False, ) def export(self, **kwargs: Any) -> Response: - """Export charts + """Download multiple charts as YAML files. --- get: - description: >- - Exports multiple charts and downloads them as YAML files + summary: Download multiple charts as YAML files parameters: - in: query name: q @@ -822,11 +818,10 @@ def export(self, **kwargs: Any) -> Response: log_to_statsd=False, ) def favorite_status(self, **kwargs: Any) -> Response: - """Favorite stars for Charts + """Check favorited charts for current user. --- get: - description: >- - Check favorited dashboards for current user + summary: Check favorited charts for current user parameters: - in: query name: q @@ -871,11 +866,10 @@ def favorite_status(self, **kwargs: Any) -> Response: 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: >- - Marks the chart as favorite for the current user + summary: Mark the chart as favorite for the current user parameters: - in: path schema: @@ -915,11 +909,10 @@ def add_favorite(self, pk: int) -> Response: 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: >- - Remove the chart from the user favorite list + summary: Remove the chart from the user favorite list parameters: - in: path schema: @@ -959,11 +952,10 @@ def remove_favorite(self, pk: int) -> Response: log_to_statsd=False, ) def warm_up_cache(self) -> Response: - """ + """Warm up the cache for the chart. --- put: - summary: >- - Warms up the cache for the chart + summary: Warm 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 @@ def warm_up_cache(self) -> Response: ) @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: diff --git a/superset/charts/data/api.py b/superset/charts/data/api.py index 0026650485e75..b67aa6886b219 100644 --- a/superset/charts/data/api.py +++ b/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 @@ def get_data(self, pk: int) -> Response: ) def data(self) -> Response: """ - Takes a query context constructed in the client and returns payload - data response for the given query. + Take a query context constructed in the client and return payload + 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 @@ def data(self) -> Response: ) 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. diff --git a/superset/charts/schemas.py b/superset/charts/schemas.py index 545845f7f2e32..6476c409ec965 100644 --- a/superset/charts/schemas.py +++ b/superset/charts/schemas.py @@ -123,23 +123,17 @@ 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": { - "get": { - "description": "Several metadata information about chart API endpoints.", - } - }, + "info": {"get": {"summary": "Get metadata information about this API resource"}}, "related": { "get": { "description": "Get a list of all possible owners for a chart. " diff --git a/superset/css_templates/api.py b/superset/css_templates/api.py index f7688afe03382..ee5d5fac703ef 100644 --- a/superset/css_templates/api.py +++ b/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: >- - Deletes multiple css templates in a bulk operation. + summary: Bulk delete CSS templates parameters: - in: query name: q diff --git a/superset/css_templates/schemas.py b/superset/css_templates/schemas.py index e8243c20792c4..26bcc61a756ff 100644 --- a/superset/css_templates/schemas.py +++ b/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"}}, - "put": {"put": {"description": "Update a CSS template"}}, - "delete": {"delete": {"description": "Delete CSS template"}}, + "post": {"post": {"summary": "Create a CSS template"}}, + "put": {"put": {"summary": "Update a 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"}} diff --git a/superset/dashboards/api.py b/superset/dashboards/api.py index 32d080b71b979..60dd7949d266c 100644 --- a/superset/dashboards/api.py +++ b/superset/dashboards/api.py @@ -312,11 +312,10 @@ def get( dash: Dashboard, add_extra_log_payload: Callable[..., None] = lambda **kwargs: None, ) -> Response: - """Gets a dashboard + """Get a dashboard. --- get: - description: >- - Get a dashboard + summary: Get a dashboard parameters: - in: path schema: @@ -367,9 +366,10 @@ def get( 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 @@ def get_datasets(self, id_or_slug: str) -> Response: 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: >- - Get the chart definitions for a given dashboard + summary: Get a dashboard's chart definitions. parameters: - in: path schema: @@ -494,11 +493,10 @@ def get_charts(self, id_or_slug: str) -> Response: ) @requires_json def post(self) -> Response: - """Creates a new Dashboard + """Create a new dashboard. --- post: - description: >- - Create a new Dashboard. + summary: Create a new dashboard requestBody: description: Dashboard schema required: true @@ -556,11 +554,10 @@ def post(self) -> Response: ) @requires_json def put(self, pk: int) -> Response: - """Changes a Dashboard + """Update a dashboard. --- put: - description: >- - Changes a Dashboard. + summary: Update a dashboard parameters: - in: path schema: @@ -641,11 +638,10 @@ def put(self, pk: int) -> Response: log_to_statsd=False, ) def delete(self, pk: int) -> Response: - """Deletes a Dashboard + """Delete a dashboard. --- delete: - description: >- - Deletes a Dashboard. + summary: Delete a dashboard parameters: - in: path schema: @@ -698,11 +694,10 @@ def delete(self, pk: int) -> Response: log_to_statsd=False, ) def bulk_delete(self, **kwargs: Any) -> Response: - """Delete bulk Dashboards + """Bulk delete dashboards. --- delete: - description: >- - Deletes multiple Dashboards in a bulk operation. + summary: Bulk delete dashboards parameters: - in: query name: q @@ -759,11 +754,10 @@ def bulk_delete(self, **kwargs: Any) -> Response: 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: >- - Exports multiple Dashboards and downloads them as YAML files. + summary: Download multiple dashboards as YAML files parameters: - in: query name: q @@ -844,11 +838,12 @@ def export(self, **kwargs: Any) -> Response: # pylint: disable=too-many-locals 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 @@ def thumbnail(self, pk: int, digest: str, **kwargs: Any) -> WerkzeugResponse: log_to_statsd=False, ) def favorite_status(self, **kwargs: Any) -> Response: - """Favorite Stars for Dashboards + """Check favorited dashboards for current user. --- get: - description: >- - Check favorited dashboards for current user + summary: Check favorited dashboards for current user parameters: - in: query name: q @@ -998,11 +992,10 @@ def favorite_status(self, **kwargs: Any) -> Response: 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: >- - Marks the dashboard as favorite for the current user + summary: Mark the dashboard as favorite for the current user parameters: - in: path schema: @@ -1042,11 +1035,10 @@ def add_favorite(self, pk: int) -> Response: 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: >- - Remove the dashboard from the user favorite list + summary: Remove the dashboard from the user favorite list parameters: - in: path schema: @@ -1085,9 +1077,10 @@ def remove_favorite(self, pk: int) -> Response: ) @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 @@ def import_(self) -> Response: ) @with_dashboard def get_embedded(self, dashboard: Dashboard) -> Response: - """Response - Returns the dashboard's embedded configuration + """Get the dashboard's embedded configuration. --- get: - description: >- - Returns the dashboard's embedded configuration + summary: Get the dashboard's embedded configuration parameters: - in: path schema: @@ -1254,12 +1245,10 @@ def get_embedded(self, dashboard: Dashboard) -> Response: ) @with_dashboard def set_embedded(self, dashboard: Dashboard) -> Response: - """Response - Sets a dashboard's embedded configuration. + """Set a dashboard's embedded configuration. --- post: - description: >- - Sets a dashboard's embedded configuration. + summary: Set a dashboard's embedded configuration parameters: - in: path schema: @@ -1335,12 +1324,10 @@ def set_embedded(self, dashboard: Dashboard) -> Response: ) @with_dashboard def delete_embedded(self, dashboard: Dashboard) -> Response: - """Response - Removes a dashboard's embedded configuration. + """Delete a dashboard's embedded configuration. --- delete: - description: >- - Removes a dashboard's embedded configuration. + summary: Delete a dashboard's embedded configuration parameters: - in: path schema: @@ -1377,10 +1364,10 @@ def delete_embedded(self, dashboard: Dashboard) -> Response: ) @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: diff --git a/superset/dashboards/filter_sets/api.py b/superset/dashboards/filter_sets/api.py index b101300f29c61..5a2bf01923f32 100644 --- a/superset/dashboards/filter_sets/api.py +++ b/superset/dashboards/filter_sets/api.py @@ -131,12 +131,10 @@ def _init_properties(self) -> None: @permission_name("get") @rison(get_list_schema) def get_list(self, dashboard_id: int, **kwargs: Any) -> Response: - """ - Gets a dashboard's Filter sets - --- + """Get a dashboard's list of filter sets. + --- get: - description: >- - Get a dashboard's list of filter sets + summary: Get a dashboard's list of filter sets parameters: - in: path schema: @@ -198,12 +196,10 @@ def get_list(self, dashboard_id: int, **kwargs: Any) -> Response: ) @requires_json def post(self, dashboard_id: int) -> Response: - """ - Creates a new Dashboard's Filter Set + """Create a new dashboard's filter set. --- post: - description: >- - Create a new Dashboard's Filter Set. + summary: Create a new dashboard's filter set parameters: - in: path schema: @@ -265,11 +261,10 @@ def post(self, dashboard_id: int) -> Response: ) @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: >- - Changes a Dashboard's Filter set. + summary: Update a dashboard's filter set parameters: - in: path schema: @@ -336,12 +331,10 @@ def put(self, dashboard_id: int, pk: int) -> Response: log_to_statsd=False, ) def delete(self, dashboard_id: int, pk: int) -> Response: - """ - Deletes a Dashboard's FilterSet + """Delete a dashboard's filter set. --- delete: - description: >- - Deletes a Dashboard. + summary: Delete a dashboard's filter set parameters: - in: path schema: diff --git a/superset/dashboards/filter_state/api.py b/superset/dashboards/filter_state/api.py index a1b855ca9ee6e..9e0720646a05c 100644 --- a/superset/dashboards/filter_state/api.py +++ b/superset/dashboards/filter_state/api.py @@ -54,11 +54,10 @@ def get_delete_command(self) -> type[DeleteFilterStateCommand]: log_to_statsd=False, ) def post(self, pk: int) -> Response: - """Stores a new value. + """Create a dashboard's filter state. --- post: - description: >- - Stores a new value. + summary: Create a dashboard's filter state parameters: - in: path schema: @@ -104,11 +103,10 @@ def post(self, pk: int) -> Response: 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: >- - Updates an existing value. + summary: Update a dashboard's filter state value parameters: - in: path schema: @@ -160,11 +158,10 @@ def put(self, pk: int, key: str) -> Response: log_to_statsd=False, ) def get(self, pk: int, key: str) -> Response: - """Retrives a value. + """Get a dashboard's filter state value. --- get: - description: >- - Retrives a value. + summary: Get a dashboard's filter state value parameters: - in: path schema: @@ -206,11 +203,10 @@ def get(self, pk: int, key: str) -> Response: log_to_statsd=False, ) def delete(self, pk: int, key: str) -> Response: - """Deletes a value. + """Delete a dashboard's filter state value. --- delete: - description: >- - Deletes a value. + summary: Delete a dashboard's filter state value parameters: - in: path schema: diff --git a/superset/dashboards/permalink/api.py b/superset/dashboards/permalink/api.py index e5528cdb59672..0a786d1def2f9 100644 --- a/superset/dashboards/permalink/api.py +++ b/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: >- - Stores a new permanent link. + summary: Create a new dashboard's permanent link parameters: - in: path schema: @@ -122,11 +121,10 @@ def post(self, pk: str) -> Response: log_to_statsd=False, ) def get(self, key: str) -> Response: - """Retrives permanent link state for dashboard. + """Get dashboard's permanent link state. --- get: - description: >- - Retrives dashboard state associated with a permanent link. + summary: Get dashboard's permanent link state parameters: - in: path schema: diff --git a/superset/dashboards/schemas.py b/superset/dashboards/schemas.py index 8549393dd4c5b..b5a12737ad217 100644 --- a/superset/dashboards/schemas.py +++ b/superset/dashboards/schemas.py @@ -69,20 +69,16 @@ 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": { - "get": { - "description": "Several metadata information about dashboard API " - "endpoints.", - } - }, + "info": {"get": {"summary": "Get metadata information about this API resource"}}, "related": { "get": {"description": "Get a list of all possible owners for a dashboard."} }, diff --git a/superset/databases/api.py b/superset/databases/api.py index caa46d3164545..ae9cd60188950 100644 --- a/superset/databases/api.py +++ b/superset/databases/api.py @@ -71,6 +71,7 @@ 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("//connection", methods=("GET",)) @protect() @safe @@ -241,8 +245,7 @@ def get_connection(self, pk: int) -> Response: """Get database connection info. --- get: - summary: >- - Get a database connection info + summary: Get a database connection info parameters: - in: path schema: @@ -282,11 +285,10 @@ def get_connection(self, pk: int) -> Response: @protect() @safe def get(self, pk: int, **kwargs: Any) -> Response: - """Get a database + """Get a database. --- get: - description: >- - Get a database + summary: Get a database parameters: - in: path schema: @@ -329,11 +331,10 @@ def get(self, pk: int, **kwargs: Any) -> Response: ) @requires_json def post(self) -> FlaskResponse: - """Creates a new Database + """Create a new database. --- post: - description: >- - Create a new Database. + summary: Create a new database requestBody: description: Database schema required: true @@ -415,11 +416,10 @@ def post(self) -> FlaskResponse: ) @requires_json def put(self, pk: int) -> Response: - """Changes a Database + """Update a database. --- put: - description: >- - Changes a Database. + summary: Change a database parameters: - in: path schema: @@ -498,11 +498,10 @@ def put(self, pk: int) -> Response: log_to_statsd=False, ) def delete(self, pk: int) -> Response: - """Deletes a Database + """Delete a database. --- delete: - description: >- - Deletes a Database. + summary: Delete a database parameters: - in: path schema: @@ -555,10 +554,10 @@ def delete(self, pk: int) -> Response: 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 @@ def schemas(self, pk: int, **kwargs: Any) -> FlaskResponse: 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 @@ def tables(self, pk: int, **kwargs: Any) -> FlaskResponse: 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 @@ def table_metadata( def table_extra_metadata( self, database: Database, table_name: str, schema_name: str ) -> FlaskResponse: - """Table schema info + """Get table extra metadata. --- get: - summary: >- - Get table extra metadata + summary: 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 @@ def table_extra_metadata( 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 @@ def select_star( ) @requires_json def test_connection(self) -> FlaskResponse: - """Tests a database connection + """Test a database connection. --- post: - description: >- - Tests a database connection + summary: Test a database connection requestBody: description: Database schema required: true @@ -920,11 +917,10 @@ def test_connection(self) -> FlaskResponse: 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: - Get charts and dashboards count associated to a database + summary: Get charts and dashboards count associated to a database parameters: - in: path name: pk @@ -987,13 +983,12 @@ def related_objects(self, pk: int) -> Response: log_to_statsd=False, ) def validate_sql(self, pk: int) -> FlaskResponse: - """ + """Validate that arbitrary SQL is acceptable for the given database. --- post: - summary: >- - Validates that arbitrary sql is acceptable for the given database + summary: Validate arbitrary SQL description: >- - Validates arbitrary SQL. + Validates that arbitrary SQL is acceptable for the given database. parameters: - in: path schema: @@ -1049,10 +1044,10 @@ def validate_sql(self, pk: int) -> FlaskResponse: 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 @@ def export(self, **kwargs: Any) -> Response: ) @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 @@ def import_(self) -> Response: 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: - Get function names supported by a database + summary: Get function names supported by a database parameters: - in: path name: pk @@ -1273,11 +1268,10 @@ def function_names(self, pk: int) -> Response: log_to_statsd=False, ) def available(self) -> Response: - """Return names of databases currently available + """Get names of databases currently available. --- get: - description: - Get names of databases currently available + summary: Get names of databases currently available responses: 200: description: Database names @@ -1386,11 +1380,10 @@ def available(self) -> Response: ) @requires_json def validate_parameters(self) -> FlaskResponse: - """validates database connection parameters + """Validate database connection parameters. --- post: - description: >- - Validates parameters used to connect to a database + summary: Validate database connection parameters requestBody: description: DB-specific parameters required: true @@ -1442,11 +1435,10 @@ def validate_parameters(self) -> FlaskResponse: log_to_statsd=False, ) def delete_ssh_tunnel(self, pk: int) -> Response: - """Deletes a SSH Tunnel + """Delete a SSH tunnel. --- delete: - description: >- - Deletes a SSH Tunnel. + summary: Delete a SSH tunnel parameters: - in: path schema: @@ -1505,11 +1497,10 @@ def delete_ssh_tunnel(self, pk: int) -> Response: 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: - The list of the database schemas where to upload information + summary: The list of the database schemas where to upload information parameters: - in: path name: pk diff --git a/superset/databases/schemas.py b/superset/databases/schemas.py index 798fbcf91131e..abba9036a1efd 100644 --- a/superset/databases/schemas.py +++ b/superset/databases/schemas.py @@ -150,6 +150,18 @@ 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: """ diff --git a/superset/datasets/api.py b/superset/datasets/api.py index 7b46544443d64..70bf03936a6ad 100644 --- a/superset/datasets/api.py +++ b/superset/datasets/api.py @@ -65,6 +65,7 @@ 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: >- - Create a new Dataset + summary: Create a new dataset requestBody: description: Dataset schema required: true @@ -333,11 +336,10 @@ def post(self) -> Response: ) @requires_json def put(self, pk: int) -> Response: - """Changes a Dataset + """Update a dataset. --- put: - description: >- - Changes a Dataset + summary: Update a dataset parameters: - in: path schema: @@ -419,11 +421,10 @@ def put(self, pk: int) -> Response: log_to_statsd=False, ) def delete(self, pk: int) -> Response: - """Deletes a Dataset + """Delete a Dataset. --- delete: - description: >- - Deletes a Dataset + summary: Delete a dataset parameters: - in: path schema: @@ -476,11 +477,10 @@ def delete(self, pk: int) -> Response: 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: >- - Exports multiple datasets and downloads them as YAML files + summary: Download multiple datasets as YAML files parameters: - in: query name: q @@ -560,11 +560,10 @@ def export(self, **kwargs: Any) -> Response: # pylint: disable=too-many-locals ) @requires_json def duplicate(self) -> Response: - """Duplicates a Dataset + """Duplicate a dataset. --- post: - description: >- - Duplicates a Dataset + summary: Duplicate a dataset requestBody: description: Dataset schema required: true @@ -630,11 +629,10 @@ def duplicate(self) -> Response: log_to_statsd=False, ) def refresh(self, pk: int) -> Response: - """Refresh a Dataset + """Refresh and update columns of a dataset. --- put: - description: >- - Refreshes and updates columns of a dataset + summary: Refresh and update columns of a dataset parameters: - in: path schema: @@ -687,11 +685,10 @@ def refresh(self, pk: int) -> Response: 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: - Get charts and dashboards count associated to a dataset + summary: Get charts and dashboards count associated to a dataset parameters: - in: path name: pk @@ -749,11 +746,10 @@ def related_objects(self, pk: int) -> Response: log_to_statsd=False, ) def bulk_delete(self, **kwargs: Any) -> Response: - """Delete bulk Datasets + """Bulk delete datasets. --- delete: - description: >- - Deletes multiple Datasets in a bulk operation. + summary: Bulk delete datasets parameters: - in: query name: q @@ -811,9 +807,10 @@ def bulk_delete(self, **kwargs: Any) -> Response: ) @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 @@ def import_(self) -> Response: 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 @@ def get_or_create_dataset(self) -> Response: log_to_statsd=False, ) def warm_up_cache(self) -> Response: - """ + """Warm up the cache for each chart powered by the given table. --- put: - summary: >- - Warms up the cache for each chart powered by the given table + summary: Warm 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. diff --git a/superset/datasets/columns/api.py b/superset/datasets/columns/api.py index 11a662953aac4..0aafab5d39dc9 100644 --- a/superset/datasets/columns/api.py +++ b/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: >- - Delete a Dataset column + summary: Delete a dataset column parameters: - in: path schema: diff --git a/superset/datasets/metrics/api.py b/superset/datasets/metrics/api.py index 34e4a3e898a87..28ec9474e2b8d 100644 --- a/superset/datasets/metrics/api.py +++ b/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: >- - Delete a Dataset metric + summary: Delete a dataset metric parameters: - in: path schema: diff --git a/superset/datasets/schemas.py b/superset/datasets/schemas.py index c422f93f0a25a..4da0cdb400638 100644 --- a/superset/datasets/schemas.py +++ b/superset/datasets/schemas.py @@ -28,6 +28,19 @@ 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( diff --git a/superset/datasource/api.py b/superset/datasource/api.py index 6399d197e0049..0c4338e3496dd 100644 --- a/superset/datasource/api.py +++ b/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 diff --git a/superset/embedded/api.py b/superset/embedded/api.py index 229ecc81c94b8..ae800bf2b9b2a 100644 --- a/superset/embedded/api.py +++ b/superset/embedded/api.py @@ -68,12 +68,10 @@ def ensure_embedded_enabled(self) -> Optional[Response]: ) # pylint: disable=arguments-differ, arguments-renamed) def get(self, uuid: str) -> Response: - """Response - Returns the dashboard's embedded configuration + """Get the dashboard's embedded configuration. --- get: - description: >- - Returns the dashboard's embedded configuration + summary: Get the dashboard's embedded configuration parameters: - in: path schema: diff --git a/superset/explore/api.py b/superset/explore/api.py index 351229bde170a..ebda161beadb9 100644 --- a/superset/explore/api.py +++ b/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) - in a single endpoint. + """Assemble Explore related information (form_data, slice, dataset) + in a single endpoint. --- get: - summary: >- - Assembles Explore related information (form_data, slice, dataset) - in a single endpoint. + summary: Assemble Explore related information in a single endpoint description: >- - Assembles Explore related information (form_data, slice, dataset) - in a single endpoint.

+ Assembles Explore related information (form_data, slice, dataset) in a + single endpoint.

The information can be assembled from:
- The cache using a form_data_key
- The metadata database using a permalink_key
diff --git a/superset/explore/form_data/api.py b/superset/explore/form_data/api.py index 3eab98e547e6a..36489ca44974d 100644 --- a/superset/explore/form_data/api.py +++ b/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: >- - Stores a new form_data. + summary: Create a new form_data parameters: - in: query schema: @@ -122,11 +121,10 @@ def post(self) -> Response: ) @requires_json def put(self, key: str) -> Response: - """Updates an existing form_data. + """Update an existing form_data. --- put: - description: >- - Updates an existing form_data. + summary: Update an existing form_data parameters: - in: path schema: @@ -195,11 +193,10 @@ def put(self, key: str) -> Response: log_to_statsd=True, ) def get(self, key: str) -> Response: - """Retrives a form_data. + """Get a form_data. --- get: - description: >- - Retrives a form_data. + summary: Get a form_data parameters: - in: path schema: @@ -247,11 +244,10 @@ def get(self, key: str) -> Response: log_to_statsd=True, ) def delete(self, key: str) -> Response: - """Deletes a form_data. + """Delete a form_data. --- delete: - description: >- - Deletes a form_data. + summary: Delete a form_data parameters: - in: path schema: diff --git a/superset/explore/permalink/api.py b/superset/explore/permalink/api.py index 7df29a3a72dfd..f03e5f7962d0a 100644 --- a/superset/explore/permalink/api.py +++ b/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: >- - Stores a new permanent link. + summary: Create a new permanent link requestBody: required: true content: @@ -119,11 +118,10 @@ def post(self) -> Response: log_to_statsd=False, ) def get(self, key: str) -> Response: - """Retrives permanent link state for chart. + """Get chart's permanent link state. --- get: - description: >- - Retrives chart state associated with a permanent link. + summary: Get chart's permanent link state parameters: - in: path schema: diff --git a/superset/importexport/api.py b/superset/importexport/api.py index 5fbf3747e8eb8..f385d04fafe6b 100644 --- a/superset/importexport/api.py +++ b/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 @@ def export(self) -> Response: ) @requires_form_data def import_(self) -> Response: - """Import multiple assets + """Import multiple assets. --- post: + summary: Import multiple assets requestBody: required: true content: diff --git a/superset/queries/api.py b/superset/queries/api.py index 2b0173ec163be..9568542f76f0b 100644 --- a/superset/queries/api.py +++ b/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 @@ def get_updated_since(self, **kwargs: Any) -> FlaskResponse: ) @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 diff --git a/superset/queries/saved_queries/api.py b/superset/queries/saved_queries/api.py index 327a2ac4cdd21..69e1a6191bca5 100644 --- a/superset/queries/saved_queries/api.py +++ b/superset/queries/saved_queries/api.py @@ -178,11 +178,10 @@ def pre_update(self, item: SavedQuery) -> None: @statsd_metrics @rison(get_delete_ids_schema) def bulk_delete(self, **kwargs: Any) -> Response: - """Delete bulk Saved Queries + """Bulk delete saved queries. --- delete: - description: >- - Deletes multiple saved queries in a bulk operation. + summary: Bulk delete saved queries parameters: - in: query name: q @@ -231,11 +230,10 @@ def bulk_delete(self, **kwargs: Any) -> Response: @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: >- - Exports multiple saved queries and downloads them as YAML files + summary: Download multiple saved queries as YAML files parameters: - in: query name: q @@ -296,9 +294,10 @@ def export(self, **kwargs: Any) -> Response: ) @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: diff --git a/superset/queries/saved_queries/schemas.py b/superset/queries/saved_queries/schemas.py index 1fbaf758a95a2..7c314e63911d0 100644 --- a/superset/queries/saved_queries/schemas.py +++ b/superset/queries/saved_queries/schemas.py @@ -18,22 +18,20 @@ from marshmallow.validate import Length openapi_spec_methods_override = { - "get": { - "get": { - "description": "Get a saved query", - } - }, + "get": {"get": {"summary": "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"}}, - "put": {"put": {"description": "Update a saved query"}}, - "delete": {"delete": {"description": "Delete saved query"}}, + "post": {"post": {"summary": "Create a saved query"}}, + "put": {"put": {"summary": "Update a 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"}} diff --git a/superset/queries/schemas.py b/superset/queries/schemas.py index b4727a3934a4f..9e0c9f834319e 100644 --- a/superset/queries/schemas.py +++ b/superset/queries/schemas.py @@ -22,10 +22,11 @@ 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.", } diff --git a/superset/reports/api.py b/superset/reports/api.py index eb6ddcfa7fa48..3116aef3b825f 100644 --- a/superset/reports/api.py +++ b/superset/reports/api.py @@ -245,11 +245,10 @@ def ensure_alert_reports_enabled(self) -> Optional[Response]: log_to_statsd=False, ) def delete(self, pk: int) -> Response: - """Delete a Report Schedule + """Delete a report schedule. --- delete: - description: >- - Delete a Report Schedule + summary: Delete a report schedule parameters: - in: path schema: @@ -299,11 +298,10 @@ def delete(self, pk: int) -> Response: def post( self, ) -> Response: - """Creates a new Report Schedule + """Create a new report schedule. --- post: - description: >- - Create a new Report Schedule + summary: Create a new report schedule requestBody: description: Report Schedule schema required: true @@ -372,11 +370,10 @@ def post( @permission_name("put") @requires_json def put(self, pk: int) -> Response: - """Updates an Report Schedule + """Update a report schedule. --- put: - description: >- - Updates a Report Schedule + summary: Update a report schedule parameters: - in: path schema: @@ -458,11 +455,10 @@ def put(self, pk: int) -> Response: log_to_statsd=False, ) def bulk_delete(self, **kwargs: Any) -> Response: - """Delete bulk Report Schedule layers + """Bulk delete report schedules. --- delete: - description: >- - Deletes multiple report schedules in a bulk operation. + summary: Bulk delete report schedules parameters: - in: query name: q diff --git a/superset/reports/logs/api.py b/superset/reports/logs/api.py index f0c272caee7c7..db307039bfb55 100644 --- a/superset/reports/logs/api.py +++ b/superset/reports/logs/api.py @@ -99,11 +99,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 report schedule logs + """Get a list of report schedule logs. --- get: - description: >- - Get a list of report schedule logs + summary: Get a list of report schedule logs parameters: - in: path schema: @@ -160,11 +159,10 @@ def get_list( # pylint: disable=arguments-differ 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: >- - Get a report schedule log + summary: Get a report schedule log parameters: - in: path schema: diff --git a/superset/reports/logs/schemas.py b/superset/reports/logs/schemas.py index bec162fbcf578..6459223523bb8 100644 --- a/superset/reports/logs/schemas.py +++ b/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.", diff --git a/superset/reports/schemas.py b/superset/reports/schemas.py index 50439160f1221..cfca8387ac1d8 100644 --- a/superset/reports/schemas.py +++ b/superset/reports/schemas.py @@ -32,18 +32,20 @@ ) 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"}}, - "put": {"put": {"description": "Update a report schedule"}}, - "delete": {"delete": {"description": "Delete a report schedule"}}, + "post": {"post": {"summary": "Create a report schedule"}}, + "put": {"put": {"summary": "Update 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"}} diff --git a/superset/row_level_security/api.py b/superset/row_level_security/api.py index 7bf00e92f74f7..0a823f74d627d 100644 --- a/superset/row_level_security/api.py +++ b/superset/row_level_security/api.py @@ -38,6 +38,7 @@ 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: >- - Create a new RLS Rule + summary: Create a new RLS rule requestBody: description: RLS schema required: true @@ -216,11 +219,10 @@ def post(self) -> Response: log_to_statsd=False, ) def put(self, pk: int) -> Response: - """Updates an RLS Rule + """Update an RLS rule. --- put: - description: >- - Updates an RLS Rule + summary: Update an RLS rule parameters: - in: path schema: @@ -305,11 +307,10 @@ def put(self, pk: int) -> Response: log_to_statsd=False, ) def bulk_delete(self, **kwargs: Any) -> Response: - """Delete bulk RLS rules + """Bulk delete RLS rules. --- delete: - description: >- - Deletes multiple RLS rules in a bulk operation. + summary: Bulk delete RLS rules parameters: - in: query name: q diff --git a/superset/row_level_security/schemas.py b/superset/row_level_security/schemas.py index 617f2b04dc467..6c8249b875a05 100644 --- a/superset/row_level_security/schemas.py +++ b/superset/row_level_security/schemas.py @@ -37,6 +37,21 @@ 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() diff --git a/superset/security/api.py b/superset/security/api.py index a45c5ce3eb4f6..b4a306975976a 100644 --- a/superset/security/api.py +++ b/superset/security/api.py @@ -88,12 +88,10 @@ class SecurityRestApi(BaseSupersetApi): @statsd_metrics @permission_name("read") def csrf_token(self) -> Response: - """ - Return the csrf token + """Get the CSRF token. --- get: - description: >- - Fetch the CSRF token + summary: Get the CSRF token responses: 200: description: Result contains the CSRF token @@ -118,12 +116,10 @@ def csrf_token(self) -> Response: @statsd_metrics @permission_name("grant_guest_token") def guest_token(self) -> Response: - """Response - Returns a guest token that can be used for auth in embedded Superset + """Get a guest token that can be used for auth in embedded Superset. --- post: - description: >- - Fetches a guest token + summary: Get a guest token requestBody: description: Parameters for the guest token required: true diff --git a/superset/sqllab/api.py b/superset/sqllab/api.py index 72d1558c046cc..ebf7fab32afd9 100644 --- a/superset/sqllab/api.py +++ b/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: >- - Estimates the SQL query execution cost + summary: Estimate the SQL query execution cost requestBody: description: SQL query and params required: true @@ -144,11 +143,10 @@ def estimate_query_cost(self) -> Response: 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: >- - Exports the SQL query results to a CSV + summary: Export the SQL query results to a CSV parameters: - in: path schema: @@ -206,11 +204,10 @@ def export_csv(self, client_id: str) -> CsvResponse: 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: >- - Gets the result of a SQL query execution + summary: Get the result of a SQL query execution parameters: - in: query name: q @@ -260,11 +257,10 @@ def get_results(self, **kwargs: Any) -> FlaskResponse: log_to_statsd=False, ) def execute_sql_query(self) -> FlaskResponse: - """Executes a SQL query + """Execute a SQL query. --- post: - description: >- - Starts the execution of a SQL query + summary: Execute a SQL query requestBody: description: SQL query and params required: true diff --git a/superset/tags/api.py b/superset/tags/api.py index 21791a6ef01e2..a12461e8e4635 100644 --- a/superset/tags/api.py +++ b/superset/tags/api.py @@ -140,11 +140,12 @@ def __repr__(self) -> str: 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 @@ def add_objects(self, object_type: ObjectTypes, object_id: int) -> Response: def delete_object( self, object_type: ObjectTypes, object_id: int, tag: str ) -> Response: - """Deletes a Tagged Object + """Delete a tagged object. --- delete: - description: >- - Deletes a Tagged Object. + summary: Delete a tagged object parameters: - in: path schema: @@ -280,11 +280,12 @@ def delete_object( 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 @@ def bulk_delete(self, **kwargs: Any) -> Response: 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: >- - Gets all objects associated with a Tag. + summary: Get all objects associated with a tag parameters: - in: path schema: diff --git a/superset/tags/schemas.py b/superset/tags/schemas.py index 71ab005bbc300..f519901a8bb84 100644 --- a/superset/tags/schemas.py +++ b/superset/tags/schemas.py @@ -19,23 +19,22 @@ 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": { - "get": { - "description": "Several metadata information about tag API " "endpoints.", - } - }, + "put": {"put": {"summary": "Update a tag"}}, + "delete": {"delete": {"summary": "Delete a tag"}}, + "post": {"post": {"summary": "Create a tag"}}, + "info": {"get": {"summary": "Get metadata information about tag API endpoints"}}, } diff --git a/superset/views/api.py b/superset/views/api.py index 8c3e4b825ce39..312efb947e4aa 100644 --- a/superset/views/api.py +++ b/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 @@ def query(self) -> FlaskResponse: @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 @@ def query_form_data(self) -> FlaskResponse: @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) diff --git a/superset/views/base_api.py b/superset/views/base_api.py index dca7a96b1d90c..7a5540406abcf 100644 --- a/superset/views/base_api.py +++ b/superset/views/base_api.py @@ -537,9 +537,10 @@ def delete_headless(self, pk: int) -> Response: @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 @@ def related(self, column_name: str, **kwargs: Any) -> FlaskResponse: @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: diff --git a/superset/views/log/api.py b/superset/views/log/api.py index d3699e3885991..33f4ad51d4537 100644 --- a/superset/views/log/api.py +++ b/superset/views/log/api.py @@ -31,6 +31,7 @@ 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 @@ def get_user_activity_access_error(self, user_id: int) -> Optional[FlaskResponse 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 diff --git a/superset/views/log/schemas.py b/superset/views/log/schemas.py index 303af1e7a9240..94130371f1628 100644 --- a/superset/views/log/schemas.py +++ b/superset/views/log/schemas.py @@ -26,6 +26,18 @@ }, } +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( diff --git a/superset/views/users/api.py b/superset/views/users/api.py index b9161021b2c12..5324975637d36 100644 --- a/superset/views/users/api.py +++ b/superset/views/users/api.py @@ -26,7 +26,7 @@ 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 @@ def get_me(self) -> Response: @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: