oas2mcp.normalize.spec_to_catalog
=================================

.. py:module:: oas2mcp.normalize.spec_to_catalog

.. autoapi-nested-parse::

   OpenAPI-to-catalog normalization helpers.

   Purpose:
       Convert parsed OpenAPI data into the normalized ``ApiCatalog`` model used by
       ``oas2mcp``.

   Design:
       - Accept either LangChain ``OpenAPISpec`` objects or plain dictionaries.
       - Resolve relative server URLs against the original source URI.
       - Flatten OpenAPI path items into reusable normalized operations.
       - Preserve raw fragments where useful for later inspection or enrichment.
       - Prefer normalized model field names over alias names during model
         construction to keep Python call sites valid and readable.

   .. rubric:: Examples

   .. code-block:: python

       from oas2mcp.loaders import load_openapi_spec_from_url
       from oas2mcp.normalize import openapi_spec_to_catalog

       source_uri = "https://petstore3.swagger.io/api/v3/openapi.json"
       spec = load_openapi_spec_from_url(source_uri)
       catalog = openapi_spec_to_catalog(spec, source_uri=source_uri)

       print(catalog.name)
       print(catalog.operation_count)



Functions
---------

.. autoapisummary::

   oas2mcp.normalize.spec_to_catalog.openapi_spec_to_catalog
   oas2mcp.normalize.spec_to_catalog.spec_dict_to_catalog


Module Contents
---------------

.. py:function:: openapi_spec_to_catalog(spec: langchain_community.utilities.openapi.OpenAPISpec, *, source_uri: str) -> oas2mcp.models.normalized.ApiCatalog

   Normalize a LangChain ``OpenAPISpec`` into an ``ApiCatalog``.

   :param spec: The parsed LangChain OpenAPI spec.
   :param source_uri: The URI from which the spec originated.

   :returns: A normalized ``ApiCatalog``.

   :raises ValueError: If ``source_uri`` is empty.

   .. rubric:: Examples

   .. code-block:: python

       from oas2mcp.loaders import load_openapi_spec_from_url
       from oas2mcp.normalize import openapi_spec_to_catalog

       source_uri = "https://petstore3.swagger.io/api/v3/openapi.json"
       spec = load_openapi_spec_from_url(source_uri)
       catalog = openapi_spec_to_catalog(spec, source_uri=source_uri)


.. py:function:: spec_dict_to_catalog(spec_dict: collections.abc.Mapping[str, Any], *, source_uri: str) -> oas2mcp.models.normalized.ApiCatalog

   Normalize a dumped OpenAPI specification into an ``ApiCatalog``.

   :param spec_dict: A plain-Python OpenAPI specification mapping.
   :param source_uri: The URI from which the spec originated. This is used for
                      source tracking and for resolving relative server URLs.

   :returns: A normalized ``ApiCatalog``.

   :raises ValueError: If ``source_uri`` is empty.

   .. rubric:: Examples

   .. code-block:: python

       from oas2mcp.normalize import spec_dict_to_catalog

       catalog = spec_dict_to_catalog(
           {
               "openapi": "3.1.0",
               "info": {"title": "Example API", "version": "1.0.0"},
               "paths": {},
           },
           source_uri="https://example.com/openapi.json",
       )