[Bug] Silent failure when parsing modular OpenAPI 3.1.0 specs

[vridhib]

Context

While testing the new V5 codegen workflow suggested by @deeleeramone in issue #7582, I attempted to generate an extension using the OpenAPI 3.1.0 spec (https://github.com/EodHistoricalData/EODHD-openapi) listed on EODHD's website.

Since EODHD does not host a public OpenAPI spec on their API domain, I cloned their modular OpenAPI repo (which splits 84 endpoints across different YAML files using $ref) and served it locally.

Steps to Reproduce

1. Clone the v5 branch and install openbb-cli.
2. Clone the EodHistoricalData/EODHD-openapi repo (git clone https://github.com/EodHistoricalData/EODHD-openapi) and serve the root openapi.yaml locally via python3 -m http.server 8000.
3. Run: openbb --generate-spec --server http://localhost:8000 --openapi-path /openapi.yaml --output eodhd.spec
4. Run: openbb --generate-extension --spec eodhd.spec --provider-name eodhd --output ./openbb-eodhd

Expected Behavior

The codegen parser should either successfully map the modular YAML $ref tags into OpenBB's internal command schema, or it should throw a clear ValidationError/ParseError to warn the user that the spec format is incompatible.

As noted in the CLI help docs, YAML is an accepted format:

--openapi-path PATH   Path (or full URL) to the OpenAPI document on the server. Defaults to /openapi.json. Servers that publish under a different name (e.g. NY Fed at /static/docs/markets-api.yml) need this. JSON or YAML accepted.

Actual Behavior

The tool completes without throwing a traceback, but outputs a skeleton package with zero commands, as shown here:

wrote 0 commands to eodhd.spec
  providers (1): eodhd
  routers (1): eodhd
  fetchers: 0 GET (across all providers)
  POST:     0 local-compute commands

The generated __init__.py contains an empty fetcher_dict={}. If a user sees the "success" message, they will install the package assuming it works, yet discover that it has no commands.

Environment

• OpenBB CLI v5 branch (post-merge of [V5] CLI 2.0 - Pluggable Backends, Non-TTY Default, HTTP Dispatcher, Spec Files + Codegen #7433)
• Python version: 3.11
• OS: Debian 12
• EODHD OpenAPI 3.1.0 spec (https://github.com/EodHistoricalData/EODHD-openapi)

[deeleeramone]

I see! Thanks for the report. The CLI operations work, but the failure is happening in the codegen. Fix to come!

openbb --generate-spec --server https://eodhd.com --openapi-path https://eodhistoricaldata.github.io/EODHD-openapi/openapi.yaml --output eodhd.spec

openbb --spec eodhd.spec eod --ticker AAPL.US --from 2025-06-02 --to 2025-06-06

{"ok": true, "result": [{"date": "2025-06-02", "open": 200.28, "high": 202.13, "low": 200.12, "close": 201.7, "adjusted_close": 200.903, "volume": 35423300}, {"date": "2025-06-03", "open": 201.35, "high": 203.77, "low": 200.96, "close": 203.27, "adjusted_close": 202.4668, "volume": 46381600}, {"date": "2025-06-04", "open": 202.91, "high": 206.24, "low": 202.1, "close": 202.82, "adjusted_close": 202.0185, "volume": 43604000}, {"date": "2025-06-05", "open": 203.5, "high": 204.75, "low": 200.15, "close": 200.63, "adjusted_close": 199.8372, "volume": 55126100}, {"date": "2025-06-06", "open": 203, "high": 205.7, "low": 202.05, "close": 203.92, "adjusted_close": 203.1142, "volume": 46607700}]}

[DogInfantry]

I looked into this and found the root cause.

In cli/openbb_cli/dispatchers/openapi_schema.py, resolve_ref() only handles local refs (#/...) and returns {} for anything else, and build_command_spec() in spec.py skips any path item that has no get/post key. In a modular spec each path item is {"$ref": "./paths/x.yaml#/pointer"}, so every path is dropped with no warning and the generator reports success with 0 commands.

I have a fix working locally that covers both behaviors the issue asks for:

1. A bundling pass that fetches external $ref files relative to the spec URL and inlines them recursively (depth cap for circular refs, clear error on a fetch/parse/missing-pointer failure), so modular specs like the EODHD repo work end to end.
2. A loud failure in build_spec_document(): if paths is non-empty but zero GET/POST commands are produced, it raises a clear ValueError instead of writing an empty spec.

While verifying against the EODHD spec I also hit a separate crash in the codegen type resolver on OpenAPI 3.1 nullable type arrays (type: [string, null]), which I fixed in the same change.

Verified against the EODHD spec served locally: --generate-spec now writes 82 commands (was 0) and the generated extension has a populated fetcher_dict.

I would like to work on this. Happy to open a PR against v5.

[DogInfantry]

Following up on my own comment: I see #7586 already implements the external $ref resolution and OpenAPI 3.1 type-array handling for this, and more thoroughly than what I had locally (same-origin only, redirect rejection, and document count/depth/size bounds). No need for a competing PR from me.

One small thing I did not see covered there: build_spec_document() in spec.py still writes an empty spec silently when paths is non-empty but resolves to zero GET/POST commands (for example a spec with only unsupported methods). A short guard that raises in that case would close the last silent-success path. Happy to send it as a small complementary change if that is wanted, otherwise I am glad #7586 handles the core issue.

[deeleeramone]

@DogInfantry, thanks for looking into this. I found some additional related issues and resolved them #7589. It's not a bad idea to have explicit guards against empty generations, and Exception handling in general. Surfacing the actionable info out of errors is always good. If you're able to surface real-world edge cases, that's a bonus. Feel free to open a PR with respect to those dimensions, the little things all add up!