Implementation:Bentoml BentoML OpenAPI Generation
| Knowledge Sources | |
|---|---|
| Domains | OpenAPI, API Documentation |
| Last Updated | 2026-02-13 15:00 GMT |
Overview
Generates OpenAPI 3.0.2 specifications for BentoML services, including inference endpoints, task management routes, mounted FastAPI apps, and standard error responses.
Description
The openapi module produces a complete OpenAPI specification from a BentoML Service instance. The generate_spec function is the main entry point, which:
- Iterates over mounted sub-applications (e.g., FastAPI apps) and merges their OpenAPI paths and component schemas.
- Calls generate_service_components to collect input/output schema components from all service APIs and includes exception schemas and a TaskStatusResponse schema.
- Constructs the final OpenAPISpecification with service metadata (name, version, contact info), tags (APP_TAG, INFRA_TAG), infrastructure endpoints (livez, readyz, healthz, metrics), and API routes.
The _get_api_routes function builds PathItem entries for each API endpoint. For standard APIs, it creates a POST route with request body, success response, and error responses (InvalidArgument, NotFound, InternalServerError). For task-based APIs (where api.is_task is True), it additionally generates:
- /status (GET) -- Check task status by task_id
- /get (GET) -- Retrieve task result by task_id
- /submit (POST) -- Submit a new task
- /retry (POST) -- Retry a failed task by task_id
- /cancel (PUT) -- Cancel an in-progress task by task_id
The TaskStatusResponse Pydantic model defines the structure for task status responses with fields: task_id, status (in_progress/success/failure/cancelled), created_at, and executed_at.
Usage
Use this module to auto-generate OpenAPI documentation for BentoML services, which is served at the service's docs endpoint and used by client code generators.
Code Reference
Source Location
- Repository: Bentoml_BentoML
- File: src/_bentoml_sdk/service/openapi.py
- Lines: 1-241
Signature
def generate_spec(svc: Service[t.Any], *, openapi_version: str = "3.0.2") -> OpenAPISpecification: ...
def generate_service_components(svc: Service[t.Any]) -> dict[str, t.Any]: ...
class TaskStatusResponse(pydantic.BaseModel):
task_id: str
status: t.Literal["in_progress", "success", "failure", "cancelled"]
created_at: str
executed_at: t.Optional[str]
Import
from _bentoml_sdk.service.openapi import generate_spec, generate_service_components
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| svc | Service[Any] | Yes | The BentoML Service instance to generate the spec for |
| openapi_version | str | No | OpenAPI specification version (default: "3.0.2") |
Outputs
| Name | Type | Description |
|---|---|---|
| OpenAPISpecification | OpenAPISpecification | Complete OpenAPI spec including paths, components, info, and servers |
| dict | dict[str, Any] | Schema components dictionary (from generate_service_components) |
Usage Examples
from _bentoml_sdk.service.openapi import generate_spec
# Given a BentoML service instance
spec = generate_spec(my_service)
# Access the generated spec
print(spec.info.title) # Service name
print(spec.paths.keys()) # All route paths
print(spec.components) # Schema components
# Generate with specific OpenAPI version
spec_31 = generate_spec(my_service, openapi_version="3.1.0")