oas2mcp.loaders.openapi

OpenAPI loading helpers.

Purpose:

Load OpenAPI specifications from URLs, local files, or raw text into plain Python dictionaries.

Design:

• Avoid runtime dependence on LangChain’s OpenAPISpec parser for now.

• Parse JSON first, then fall back to YAML.

• Return plain dictionaries so the normalization layer can remain stable.

• Provide backward-compatible helper names during the transition away from LangChain’s OpenAPISpec path.

Examples

from oas2mcp.loaders.openapi import load_openapi_spec_dict_from_url

spec_dict = load_openapi_spec_dict_from_url(
    "https://petstore3.swagger.io/api/v3/openapi.json",
)
print(spec_dict["openapi"])

Functions

dump_openapi_spec(→ dict[str, Any])	Convert a spec-like object into a plain dictionary.
load_openapi_spec(→ dict[str, Any])	Backward-compatible alias for generic spec loading.
load_openapi_spec_dict(→ dict[str, Any])	Load an OpenAPI-compatible specification from a URL, file, or raw text.
load_openapi_spec_dict_from_file(→ dict[str, Any])	Load an OpenAPI specification dictionary from a local file.
load_openapi_spec_dict_from_text(→ dict[str, Any])	Load an OpenAPI specification dictionary from raw text.
load_openapi_spec_dict_from_url(→ dict[str, Any])	Load an OpenAPI specification dictionary from a URL.
load_openapi_spec_from_file(→ dict[str, Any])	Backward-compatible alias for file-based spec loading.
load_openapi_spec_from_text(→ dict[str, Any])	Backward-compatible alias for text-based spec loading.
load_openapi_spec_from_url(→ dict[str, Any])	Backward-compatible alias for URL-based spec loading.
normalize_api_description_dict(→ dict[str, Any])	Normalize common API-description variants into an OpenAPI-style mapping.

Module Contents

oas2mcp.loaders.openapi.dump_openapi_spec(spec: Any) → dict[str, Any]

Convert a spec-like object into a plain dictionary.

Parameters:

spec – A plain dictionary or model-like object.

Returns:

A plain dictionary representation of the spec.

Raises:

TypeError – If spec cannot be converted into a dictionary.

Examples

data = dump_openapi_spec({"openapi": "3.1.0"})
assert data["openapi"] == "3.1.0"

oas2mcp.loaders.openapi.load_openapi_spec(source: str | pathlib.Path, *, timeout: float = 30.0, encoding: str = 'utf-8') → dict[str, Any]

Backward-compatible alias for generic spec loading.

oas2mcp.loaders.openapi.load_openapi_spec_dict(source: str | pathlib.Path, *, timeout: float = 30.0, encoding: str = 'utf-8') → dict[str, Any]

Load an OpenAPI-compatible specification from a URL, file, or raw text.

Parameters:

• source – URL, local file path, file:// URI, or raw JSON/YAML text.

• timeout – Request timeout used for URL loading.

• encoding – Text encoding used when reading local files.

Returns:

The parsed specification as a plain dictionary.

Raises:

• FileNotFoundError – If the source looks like a local file but is missing.

• ValueError – If the source cannot be parsed as JSON or YAML.

Examples

spec_dict = load_openapi_spec_dict("openapi.yaml")
spec_dict = load_openapi_spec_dict("https://example.com/openapi.json")

oas2mcp.loaders.openapi.load_openapi_spec_dict_from_file(path: str | pathlib.Path, *, encoding: str = 'utf-8') → dict[str, Any]

Load an OpenAPI specification dictionary from a local file.

Parameters:

• path – The file path to the OpenAPI specification.

• encoding – Text encoding used when reading the file.

Returns:

The parsed OpenAPI specification as a plain dictionary.

Raises:

• FileNotFoundError – If the file does not exist.

• ValueError – If the file is empty or cannot be parsed.

Examples

spec_dict = load_openapi_spec_dict_from_file("openapi.json")

oas2mcp.loaders.openapi.load_openapi_spec_dict_from_text(text: str) → dict[str, Any]

Load an OpenAPI specification dictionary from raw text.

Parameters:

text – Raw JSON or YAML OpenAPI text.

Returns:

The parsed OpenAPI specification as a plain dictionary.

Raises:

ValueError – If the text is empty or cannot be parsed into a dictionary.

Examples

spec_dict = load_openapi_spec_dict_from_text(
    '{"openapi":"3.1.0","info":{"title":"A","version":"1"},"paths":{}}'
)

oas2mcp.loaders.openapi.load_openapi_spec_dict_from_url(url: str, *, timeout: float = 30.0) → dict[str, Any]

Load an OpenAPI specification dictionary from a URL.

Parameters:

• url – The URL of the OpenAPI specification.

• timeout – Request timeout in seconds.

Returns:

The parsed OpenAPI specification as a plain dictionary.

Raises:

• httpx.HTTPError – If the request fails.

• ValueError – If the response body is empty or cannot be parsed.

Examples

spec_dict = load_openapi_spec_dict_from_url(
    "https://petstore3.swagger.io/api/v3/openapi.json",
)

oas2mcp.loaders.openapi.load_openapi_spec_from_file(path: str | pathlib.Path, *, encoding: str = 'utf-8') → dict[str, Any]

Backward-compatible alias for file-based spec loading.

oas2mcp.loaders.openapi.load_openapi_spec_from_text(text: str) → dict[str, Any]

Backward-compatible alias for text-based spec loading.

oas2mcp.loaders.openapi.load_openapi_spec_from_url(url: str, *, timeout: float = 30.0) → dict[str, Any]

Backward-compatible alias for URL-based spec loading.

oas2mcp.loaders.openapi.normalize_api_description_dict(data: dict[str, Any]) → dict[str, Any]

Normalize common API-description variants into an OpenAPI-style mapping.

Parameters:

data – Parsed JSON/YAML API description.

Returns:

A dictionary shaped like an OpenAPI document.

Raises:

ValueError – If the document is not an OpenAPI-style mapping.