Implementation:Mlflow Mlflow Generate REST API Docs

Knowledge Sources	Mlflow_Mlflow
Domains	Documentation, CodeGeneration
Last Updated	2026-02-13 20:00 GMT

Overview

Generates RST documentation for the MLflow REST API by parsing protobuf JSON definitions into a hierarchy of services, methods, messages, enums, and fields.

Description

This script reads mlflow/protos/protos.json (produced by the proto plugin) and transforms it into a complete RST documentation file for the MLflow REST API. The code is organized around several key classes:

• Field -- Represents a field within a protobuf message, handling name parsing (including oneofs), type conversion with internal RST cross-references, and description normalization.
• Value -- Represents an enum value with name and description.
• ProtoEnum -- A protobuf enum containing a list of Value objects, rendered as an RST table.
• Message -- A protobuf message containing Field objects, classified as GENERIC, REQUEST, or RESPONSE via the MsgType enum.
• Method -- An RPC method linking to its request and response messages, with HTTP endpoint path, method type, and per-method API versioning extracted from proto "since" annotations.
• Service -- A protobuf service grouping multiple Method objects with configurable ordering.
• API -- The top-level orchestrator that filters proto files, parses services/messages/enums, connects request/response messages to methods, and writes the final RST output.

The script uses the texttable library to generate ASCII tables for the RST output. It supports custom method ordering via VALID_MLFLOW_MESSAGES and service ordering via SERVICE_ORDER. Per-method API versions are sourced from the proto definitions' since_major and since_minor fields, falling back to the API-level default version.

Usage

Run this script when protobuf definitions are updated to regenerate the REST API documentation. It is typically invoked as part of the documentation build pipeline.

Code Reference

Source Location

• Repository: Mlflow_Mlflow
• File: dev/gen_rest_api.py
• Lines: 1-865

Signature

class Field:
    def __init__(self, full_path: list[str], name: str, description: str, field_type: str) -> None: ...
    @classmethod
    def parse_all_from(cls, field_list: list[dict[str, Any]]) -> list[Field]: ...

class Message:
    def __init__(self, full_path: list[str], name: str, description: str, fields: list[Field]) -> None: ...
    def to_rst(self) -> str: ...
    @classmethod
    def parse_all_from(cls, files: list[dict[str, Any]]) -> list[Message]: ...

class Method:
    def __init__(self, full_path: list[str], name: str, description: str,
                 path: str, method: str, request: list[str], response: list[str],
                 title: str | None, api_version: str | None = None) -> None: ...
    def to_rst(self) -> str: ...

class Service:
    def to_rst(self, method_order: list[str] | None = None) -> str: ...

class API:
    def __init__(self, name: str, description: str, api_version: str,
                 dst_path: Path, valid_proto_files: list[str]) -> None: ...
    def set_all(self, proto_file_list: list[dict[str, Any]],
                service_order: list[str] | None = None) -> None: ...
    def write_rst(self, method_order: list[str] | None = None) -> None: ...

def main() -> None: ...

Import

# Run from repository root (requires texttable dependency)
uv run dev/gen_rest_api.py

I/O Contract

Inputs

Name	Type	Required	Description
mlflow/protos/protos.json	JSON file	Yes	Protobuf documentation JSON generated by the proto plugin

Outputs

Name	Type	Description
docs/api_reference/source/rest-api.rst	RST file	Complete REST API documentation with endpoint tables, request/response structures, data types, and enums

Usage Examples

Basic Usage

# Generate REST API documentation from protobuf definitions
uv run dev/gen_rest_api.py

Related Pages

• Environment:Mlflow_Mlflow_Python_Runtime_Environment