[Feature] openbb-platform-api Better POST Params Discovery (#7204)

* better post params discovery

* missing sentence in readme

* nasdaq expected widgets

* codespell

* openapi_extra is expected to be not None by packagebuilder

* lint

* lint

Author: deeleeramone

openbb_platform/extensions/economy/openbb_economy/economy_router.py

@@ -870,7 +870,7 @@ async def direction_of_trade(
                 "h": 27,
             },
             "refetchInterval": False,
-            "endpoint": "/api/v1/economy/fomc_documents/download",
+            "endpoint": f"{api_prefix}/economy/fomc_documents/download",
             "params": [
                 {
                     "type": "endpoint",
@@ -915,7 +915,7 @@ async def fomc_documents(
     """
     results = await OBBject.from_query(Query(**locals()))
 
-    return results.results.content
+    return results.results.content  # type: ignore
 
 
 # This endpoint is used to download FOMC documents in Workspace.
@@ -926,11 +926,7 @@ async def fomc_documents(
 @router._api_router.post(
     "/fomc_documents/download",
     include_in_schema=False,
-    openapi_extra={
-        "widget_config": {
-            "exclude": True,
-        }
-    },
+    openapi_extra={},
 )
 async def fomc_documents_download(params: Annotated[dict, Body()]) -> list:
     """
@@ -947,7 +943,7 @@ async def fomc_documents_download(params: Annotated[dict, Body()]) -> list:
 
     urls = params.get("url", [])
 
-    results = []
+    results: list = []
     for url in urls:
         try:
             response = make_request(url)

openbb_platform/extensions/platform_api/README.md

@@ -433,10 +433,12 @@ For example, the response to submitting a form can be a Markdown widget with a c
 
 The entry in `widgets.json` will be automatically created if the conditions below are met:
 
-- GET and POST methods must share the same API route.
+- GET request defines in top-level `widget_config`:
+  - `{"form_endpoint": /path_to/form_post_endpoint}`
 - POST method takes 1 positional argument, a sub-class of Pydantic BaseModel.
   - Create a model, like annotated table fields, defining all inputs to the form.
 
+
 #### Example
 
 The code below creates a widget with a form as the input, and an output table of all submitted forms, as processed through the `IntakeForm` model.
@@ -447,15 +449,14 @@ from datetime import date as dateType
 from typing import Literal, Union
 
 # from fastapi import FastAPI
-from openbb_platform_api.query_models import FormData
 from openbb_platform_api.response_models import Data
-from pydantic import ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field
 
 # app = FastAPI()
 
 AccountTypes = Literal["General Fund", "Separately Managed", "Private Equity", "Family Office"]
 
-class GeneralIntake(FormData):
+class GeneralIntake(BaseModel):
     """Submit a form via POST request."""
 
     date_created: dateType = Field(
@@ -476,7 +477,11 @@ class GeneralIntake(FormData):
     submit: bool = Field(
         default=True,
         title="Submit",
-        type="button",  # This creates a button, when pressed the parameter is sent as True
+        json_schema_extra={
+            "x-widget_config": {
+                "type": "button",
+            },
+        }
     )
 
 
@@ -510,7 +515,7 @@ class IntakeForm(Data):
 INTAKE_FORMS: list[IntakeForm] = []
 
 
-@app.post("/general_intake")
+@app.post("/general_intake_submit")
 async def general_intake_post(data: GeneralIntake) -> bool:
     global INTAKE_FORMS
     try:
@@ -520,7 +525,14 @@ async def general_intake_post(data: GeneralIntake) -> bool:
         raise e from e
 
 
-@app.get("/general_intake")
+@app.get(
+    "/general_intake",
+    openapi_extra= {
+        "widget_config": {
+            "form_endpoint": "/general_intake_submit",
+        },
+    },
+)
 async def general_intake() -> list[IntakeForm]:
     return INTAKE_FORMS
 ```
@@ -529,6 +541,12 @@ async def general_intake() -> list[IntakeForm]:
 
 ### Omni Widget Example
 
+An Omni Widget is a POST request where all parameters are sent to the request body, along with the text input box (keyed as "prompt").
+
+The returned type can be a list of records (table), a Plotly Figure, or formatted Markdwon.
+The model will attempt to assign the correct return type dynamically.
+
+Set the response model as `OmniWidgetResponseModel`, then return `{"content": your_content}` from the endpoint.
 
 ```python
 from typing import Literal, Optional
@@ -565,7 +583,7 @@ async def create_omni_widget(item: TestOmniWidgetQueryModel):
     if item.parse_as == "chart":
         some_test_data = {
             "data": [{"type": "bar", "x": ["A", "B", "C"], "y": [1, 2, 3]}],
-            "layout": {"template": "...", "title": {"text": "Hello Chart!"}}
+            "layout": {"template": "plotly_dark", "title": {"text": "Hello Chart!"}}
         }
     elif item.parse_as == "text":
         some_test_data = f"""

openbb_platform/extensions/platform_api/openbb_platform_api/query_models.py

@@ -7,16 +7,6 @@
 from pydantic.alias_generators import to_snake
 
 
-class FormData(Data):
-    """Submit a form via POST request."""
-
-    model_config = ConfigDict(
-        extra="allow",
-        alias_generator=AliasGenerator(to_snake),
-        title="Submit Form",
-    )
-
-
 class OmniWidgetInput(Data):
     """Input for OmniWidget."""
 

openbb_platform/extensions/platform_api/openbb_platform_api/utils/openapi.py

@@ -1,5 +1,8 @@
 """OpenAPI parsing Utils."""
 
+# pylint: disable=C0302,R0912
+# flake8: noqa: PLR0912
+
 from typing import Optional
 
 from openbb_core.provider.utils.helpers import to_snake_case
@@ -937,39 +940,93 @@ def set_param(k, v):
     ):
         # Get the reference to the schema for the request body.
 
-        param_ref = (
-            schema["items"].get("$ref")
-            if "items" in schema
-            else schema.get("$ref") or schema
-        )
+        title = schema.get("title")
+        providers: list[str] = []
 
-        if isinstance(param_ref, dict) and "type" in param_ref:
-            param_ref = param_ref["type"]
+        if title and title in schema:
+            providers = [title]
+        elif title and "," in title:
+            providers = title.split(",")
+        else:
+            providers = ["Custom"]
+
+        if params := _route.get("parameters"):
+            if isinstance(params, list):
+                for _param in params:
+                    set_param(_param["name"], _param["schema"])
+            elif isinstance(params, dict):
+                for k, v in params.items():
+                    set_param(k, v)
 
-        if param_ref and isinstance(param_ref, str):
-            # Extract the schema name from the reference
-            schema_name = param_ref.split("/")[-1]
-            schema = openapi_json["components"]["schemas"].get(schema_name, schema_name)
-            props = {} if isinstance(schema, str) else schema.get("properties", {})
-
-            for k, v in props.items():
-                if target_schema and target_schema != k:
-                    continue
-                if nested_schema := v.get("$ref"):
-                    nested_schema_name = nested_schema.split("/")[-1]
-                    nested_schema = openapi_json["components"]["schemas"].get(
-                        nested_schema_name, {}
-                    )
-                    for nested_k, nested_v in nested_schema.get(
-                        "properties", {}
-                    ).items():
-                        set_param(nested_k, nested_v)
+        if "items" in schema or "$ref" in schema:
+            param_ref = (
+                schema["items"].get("$ref")
+                if "items" in schema
+                else schema.get("$ref") or schema
+            )
 
-                else:
-                    set_param(k, v)
+            if isinstance(param_ref, dict) and "type" in param_ref:
+                param_ref = param_ref["type"]
 
-            route_params: list[dict] = []
-            providers = ["custom"]
+            if param_ref and isinstance(param_ref, str):
+                # Extract the schema name from the reference
+                schema_name = param_ref.split("/")[-1]
+                schema = openapi_json["components"]["schemas"].get(
+                    schema_name, schema_name
+                )
+                props = {} if isinstance(schema, str) else schema.get("properties", {})
+
+                for k, v in props.items():
+                    if target_schema and target_schema != k:
+                        continue
+                    if nested_schema := v.get("$ref"):
+                        nested_schema_name = nested_schema.split("/")[-1]
+                        nested_schema = openapi_json["components"]["schemas"].get(
+                            nested_schema_name, {}
+                        )
+                        for nested_k, nested_v in nested_schema.get(
+                            "properties", {}
+                        ).items():
+                            set_param(nested_k, nested_v)
+
+                    else:
+                        set_param(k, v)
+
+                route_params: list[dict] = []
+
+                for new_param_values in new_params.values():
+                    _new_values = new_param_values.copy()
+                    p = process_parameter(_new_values, providers)
+                    if not p.get("exclude") and not p.get("x-widget_config", {}).get(
+                        "exclude"
+                    ):
+                        route_params.append(p)
+
+                return route_params
+        if "anyOf" in _route or "anyOf" in schema:
+            any_of_schema = (
+                schema.get("anyOf", [])
+                if "anyOf" in schema
+                else _route.get("anyOf", [])
+            )
+            for item in any_of_schema:
+                # If item is a $ref, resolve it
+                if "$ref" in item:
+                    ref_name = item["$ref"].split("/")[-1]
+                    ref_schema = openapi_json["components"]["schemas"].get(ref_name, {})
+                    if "properties" in ref_schema:
+                        for k, v in ref_schema["properties"].items():
+                            if target_schema and target_schema != k:
+                                continue
+                            set_param(k, v)
+                # If item has properties directly
+                elif "properties" in item:
+                    for k, v in item["properties"].items():
+                        if target_schema and target_schema != k:
+                            continue
+                        set_param(k, v)
+
+            route_params = []
 
             for new_param_values in new_params.values():
                 _new_values = new_param_values.copy()