To generate the openapi.yaml files, the generator imports each FastAPI app in an isolated subprocess and calls its .openapi() method directly (no running server), then applies a series of schema fixes and validation passes.
To generate the updated OpenAPI schema, run:
uv run --frozen python -m script.generate_openapi_specThe generator no longer emits one spec per microservice and merges them. It now produces:
One aggregate platform spec, built from the platform runner (nmp.platform_runner.server:create_platform_openapi_app) with plugin services deliberately excluded (NEMO_PLUGIN_SERVICES_ALLOWLIST="" — see SERVICES in script/generate_openapi_spec.py). This aggregate covers the core platform services (entities, jobs, models, inference gateway, secrets, files, platform-common, etc.) and lands in:
| File | Contents |
|---|---|
openapi/openapi.yaml |
Final merged GA + EA platform spec |
openapi/ga/openapi.yaml |
GA-only platform spec |
openapi/ea/openapi.yaml |
EA-only platform spec |
openapi/ga/individual/platform.openapi.yaml |
The platform spec before GA/EA merge |
One spec per opted-in plugin, written next to each plugin — never merged into the platform spec. A plugin opts in by declaring a [tool.nemo.openapi] table in its own pyproject.toml; discover_plugins() (script/openapi_helper/plugin_config.py) enumerates those, builds each plugin's FastAPI app via the convention loader (or a factory_override), and emits:
| Plugin | Output File |
|---|---|
| Agents | plugins/nemo-agents/openapi/openapi.yaml |
| Auditor | plugins/nemo-auditor/openapi/openapi.yaml |
| Customization | plugins/nemo-customizer/openapi/openapi.yaml |
| Data Designer | plugins/nemo-data-designer/openapi/openapi.yaml |
| Deployments | plugins/nemo-deployments/openapi/openapi.yaml |
| Evaluator | plugins/nemo-evaluator/openapi/openapi.yaml |
| Safe Synthesizer | plugins/nemo-safe-synthesizer/openapi/openapi.yaml |
The Customization spec is assembled at generation time from whichever customization contributors (nemo.customization.contributors entry points — e.g. automodel, rl, unsloth) are installed in the workspace, so its route surface depends on the synced environment. To add a new plugin to this list, add an (empty is fine) [tool.nemo.openapi] table to its pyproject.toml; if the plugin has more than one nemo.services entry point, set service_name in that table to disambiguate.
The platform GA and EA specs are merged with the --keep-versions flag to preserve version information in the final openapi.yaml.
Currently, there are some conflicts between the schemas coming from different microservices, when they are overlapping types. Some are bugs, some need to be reconciled (one of the schemas is out of date). This will be fixed in the next releases. For now, when that happens, the schemas are duplicated, with a suffix.
There are some recursive schemas that cause issues with the OpenAPI validator. These are currently fixed by removing the recursive reference and replacing it with a generic object.
The OpenAPI specification includes example requests and responses for various endpoints. These examples are generated from the /openapi/api-examples files.
As a POC, the included files have been generated with an LLM(Cursor) to analyze and extract examples from the tool calling notebooks.
Currently, the examples are manually generated from notebooks. A robust system that automatically generates examples from all notebooks will be integrated in the future to ensure comprehensive and up-to-date API documentation.
The aggregate platform spec is now generated directly from the platform runner (nmp.platform_runner.server), so it corresponds to what is actually mounted at runtime. Only the GA and EA variants of that single platform spec are merged; individual core services are no longer emitted and merged separately.