To generate the openapi.yaml file that corresponds exactly to what is implemented in each microservice, we start each microservice and fetch the /openapi.json file generated by the FastAPI server.
To generate the updated OpenAPI schema, run:
uv run --frozen python -m script.generate_openapi_specThe following table lists all the OpenAPI specifications that are merged into the final openapi.yaml file, along with their sources:
| Service | Source | Output File |
|---|---|---|
| Entity Store | Generated from entity_store.server:app |
entity-store.openapi.yaml |
| Evaluator | Generated from evaluator.server:app |
evaluator.openapi.yaml |
| Guardrails | Generated from guardrails.app:app |
guardrails.openapi.yaml |
| Customization | Generated from nemo-customizer-plugin contributor routes |
customization.openapi.yaml |
| Deployment Management | Direct copy from deployment.openapi.yaml |
deployment-management.openapi.yaml |
| Jobs | Generated from jobs.api.server:app |
jobs.openapi.yaml |
| Data Designer | Generated from data_designer.api.server:app |
data-designer.openapi.yaml |
| Auditor | Generated from auditor.server:app |
auditor.openapi.yaml |
| Safe Synthesizer API | Generated from safe_synthesizer_api.server:app |
safe-synthesizer.openapi.yaml |
| Intake | Generated from src.main:app |
intake.openapi.yaml |
| Models | Generated from models.api.server:app |
models.openapi.yaml |
| Inference Gateway | Generated from inference_gateway.api.server:create_app |
inference-gateway.openapi.yaml |
| Platform Common | Generated from nemoplatform.server:app |
nmp-common.openapi.yaml |
All 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.
Ideally, the nmp-common.openapi.yaml file would be the platform OpenAPI spec directly, but for various reasons, it is not. We should get to that point soon. Until then, we take this merging approach to have a spec that corresponds 100% to what is implemented.