From 9c7835a244ea6f9d60e191e9725a092f2b1e3462 Mon Sep 17 00:00:00 2001 From: Mehmet Salih Yavuz Date: Thu, 13 Feb 2025 20:02:45 +0300 Subject: [PATCH] docs(api): Improve api documentation for dashboard endpoints(filter_state, permalink, embedded) (#32142) --- superset/dashboards/filter_state/api.py | 74 +++++++++++++++++++++++++ superset/dashboards/permalink/api.py | 69 +++++++++++++++++++++++ superset/embedded/api.py | 32 ++++++++++- 3 files changed, 174 insertions(+), 1 deletion(-) diff --git a/superset/dashboards/filter_state/api.py b/superset/dashboards/filter_state/api.py index d3b6ce8f7..25fb7ad20 100644 --- a/superset/dashboards/filter_state/api.py +++ b/superset/dashboards/filter_state/api.py @@ -73,6 +73,80 @@ class DashboardFilterStateRestApi(TemporaryCacheRestApi): application/json: schema: $ref: '#/components/schemas/TemporaryCachePostSchema' + examples: + time_grain_filter: + summary: "Time Grain Filter" + description: "**This body should be stringified and put into the + value field.**" + value: + id: NATIVE_FILTER_ID + extraFormData: + time_grain_sqla: "P1W/1970-01-03T00:00:00Z" + filterState: + label: "Week ending Saturday" + value: + - "P1W/1970-01-03T00:00:00Z" + timecolumn_filter: + summary: "Time Column Filter" + description: "**This body should be stringified and put into the + value field.**" + value: + id: NATIVE_FILTER_ID + extraFormData: + granularity_sqla: "order_date" + filterState: + value: + - "order_date" + time_range_filter: + summary: "Time Range Filter" + description: "**This body should be stringified and put into the + value field.**" + value: + id: NATIVE_FILTER_ID + extraFormData: + time_range: >- + DATEADD(DATETIME('2025-01-16T00:00:00'), -7, day) + : 2025-01-16T00:00:00 + filterState: + value: >- + DATEADD(DATETIME('2025-01-16T00:00:00'), -7, day) + : 2025-01-16T00:00:00 + numerical_range_filter: + summary: "Numerical Range Filter" + description: "**This body should be stringified and put into the + value field.**" + value: + id: NATIVE_FILTER_ID + extraFormData: + filters: + - col: "tz_offset" + op: ">=" + val: + - 1000 + - col: "tz_offset" + op: "<=" + val: + - 2000 + filterState: + value: + - 1000 + - 2000 + label: "1000 <= x <= 2000" + value_filter: + summary: "Value Filter" + description: "**This body should be stringified and put into the + value field.**" + value: + id: NATIVE_FILTER_ID + extraFormData: + filters: + - col: "real_name" + op: "IN" + val: + - "John Doe" + filterState: + value: + - "John Doe" responses: 201: description: The value was stored successfully. diff --git a/superset/dashboards/permalink/api.py b/superset/dashboards/permalink/api.py index 208cda2a1..14e6d3cb0 100644 --- a/superset/dashboards/permalink/api.py +++ b/superset/dashboards/permalink/api.py @@ -69,6 +69,75 @@ class DashboardPermalinkRestApi(BaseSupersetApi): application/json: schema: $ref: '#/components/schemas/DashboardPermalinkStateSchema' + examples: + time_grain_filter: + summary: "Time Grain Filter" + value: + dataMask: + id: NATIVE_FILTER_ID + extraFormData: + time_grain_sqla: "P1W/1970-01-03T00:00:00Z" + filterState: + label: "Week ending Saturday" + value: + - "P1W/1970-01-03T00:00:00Z" + timecolumn_filter: + summary: "Time Column Filter" + value: + dataMask: + id: NATIVE_FILTER_ID + extraFormData: + granularity_sqla: "order_date" + filterState: + value: + - "order_date" + time_range_filter: + summary: "Time Range Filter" + value: + dataMask: + id: NATIVE_FILTER_ID + extraFormData: + time_range: >- + DATEADD(DATETIME("2025-01-16T00:00:00"), -7, day) + : 2025-01-16T00:00:00 + filterState: + value: >- + DATEADD(DATETIME("2025-01-16T00:00:00"), -7, day) + : 2025-01-16T00:00:00 + numerical_range_filter: + summary: "Numerical Range Filter" + value: + dataMask: + id: NATIVE_FILTER_ID + extraFormData: + filters: + - col: "tz_offset" + op: ">=" + val: + - 1000 + - col: "tz_offset" + op: "<=" + val: + - 2000 + filterState: + value: + - 1000 + - 2000 + label: "1000 <= x <= 200" + value_filter: + summary: "Value Filter" + value: + dataMask: + id: NATIVE_FILTER_ID + extraFormData: + filters: + - col: "real_name" + op: "IN" + val: + - "John Doe" + filterState: + value: + - "John Doe" responses: 201: description: The permanent link was stored successfully. diff --git a/superset/embedded/api.py b/superset/embedded/api.py index b907422bf..79d427ef2 100644 --- a/superset/embedded/api.py +++ b/superset/embedded/api.py @@ -71,13 +71,40 @@ class EmbeddedDashboardRestApi(BaseSupersetModelRestApi): """Get the dashboard's embedded configuration. --- get: - summary: Get the dashboard's embedded configuration + summary: >- + Get the dashboard's embedded configuration this endpoint is also used + to embed dashboards. parameters: - in: path schema: type: string name: uuid description: The embedded configuration uuid + - in: query + schema: + type: number + name: uiConfig + description: The ui config of embedded dashboard (optional). + - in: query + schema: + type: boolean + name: show_filters + description: Show filters (optional). + - in: query + schema: + type: boolean + name: expand_filters + description: Expand filters (optional). + - in: query + schema: + type: string + name: native_filters_key + description: Native filters key to apply filters. (optional). + - in: query + schema: + type: string + name: permalink_key + description: Permalink key to apply filters. (optional). responses: 200: description: Result contains the embedded dashboard configuration @@ -88,6 +115,9 @@ class EmbeddedDashboardRestApi(BaseSupersetModelRestApi): properties: result: $ref: '#/components/schemas/EmbeddedDashboardResponseSchema' + text/html: + schema: + type: string 401: $ref: '#/components/responses/401' 404: