docs(api): Improve api documentation for dashboard endpoints(filter_s…

…tate, permalink, embedded) (#32142)
apache · Feb 13, 2025 · 9c7835a · 9c7835a
1 parent ad05732
commit 9c7835a
Show file tree

Hide file tree

Showing 3 changed files with 174 additions and 1 deletion.
diff --git a/superset/dashboards/filter_state/api.py b/superset/dashboards/filter_state/api.py
@@ -73,6 +73,80 @@ def post(self, pk: int) -> Response:
               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
@@ -69,6 +69,75 @@ def post(self, pk: str) -> Response:
               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
@@ -71,13 +71,40 @@ def get(self, uuid: str) -> Response:
         """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 @@ def get(self, uuid: str) -> Response:
                     properties:
                       result:
                         $ref: '#/components/schemas/EmbeddedDashboardResponseSchema'
+                text/html:
+                    schema:
+                        type: string
             401:
               $ref: '#/components/responses/401'
             404: