ExUtcp.OpenApiConverter (ex_utcp v0.3.2)

Copy Markdown View Source

OpenAPI Converter for automatic API discovery and tool generation.

Converts OpenAPI 2.0 and 3.0 specifications into UTCP tools, enabling AI agents to interact with existing APIs directly without server modifications.

Features

  • OpenAPI 2.0 and 3.0 support
  • Automatic tool generation from API operations
  • Authentication scheme mapping
  • Parameter and response schema handling
  • Variable substitution support
  • Batch processing of multiple specs

Usage

# Convert from URL
{:ok, manual} = OpenApiConverter.convert_from_url("https://api.github.com/openapi.json")

# Convert from local file
{:ok, manual} = OpenApiConverter.convert_from_file("path/to/spec.json")

# Convert from map
{:ok, manual} = OpenApiConverter.convert(spec_map)

# Convert with custom options
{:ok, manual} = OpenApiConverter.convert(spec_map, %{
  base_url: "https://api.example.com",
  auth: %{type: "api_key", api_key: "Bearer ${API_KEY}"},
  prefix: "github"
})

Summary

Functions

convert(spec, opts \\ [])

Converts an OpenAPI specification to a UTCP manual.

convert_from_file(file_path, opts \\ [])

Converts an OpenAPI specification from a local file.

convert_from_url(url, opts \\ [])

Converts an OpenAPI specification from a URL.

convert_multiple(specs, opts \\ [])

Converts multiple OpenAPI specifications and merges them into a single manual.

validate(spec)

Validates an OpenAPI specification without converting it.

Functions

convert(spec, opts \\ [])

@spec convert(
  map(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Converts an OpenAPI specification to a UTCP manual.

Parameters

  • spec: OpenAPI specification as a map
  • opts: Optional configuration map with keys:
    • :base_url - Override base URL from spec
    • :auth - Authentication configuration
    • :prefix - Prefix for tool names
    • :include_deprecated - Include deprecated operations (default: false)
    • :filter_tags - Only include operations with these tags
    • :exclude_tags - Exclude operations with these tags

Returns

{:ok, manual} on success, {:error, reason} on failure.

convert_from_file(file_path, opts \\ [])

@spec convert_from_file(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Converts an OpenAPI specification from a local file.

Parameters

  • file_path: Path to the OpenAPI specification file
  • opts: Optional configuration (same as convert/2)

Returns

{:ok, manual} on success, {:error, reason} on failure.

convert_from_url(url, opts \\ [])

@spec convert_from_url(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Converts an OpenAPI specification from a URL.

Parameters

  • url: URL to the OpenAPI specification
  • opts: Optional configuration (same as convert/2)

Returns

{:ok, manual} on success, {:error, reason} on failure.

convert_multiple(specs, opts \\ [])

@spec convert_multiple(
  list(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Converts multiple OpenAPI specifications and merges them into a single manual.

Parameters

  • specs: List of specification sources (maps, URLs, or file paths)
  • opts: Optional configuration (same as convert/2)

Returns

{:ok, manual} on success, {:error, reason} on failure.

validate(spec)

@spec validate(map()) :: {:ok, ExUtcp.OpenApiConverter.Types.ValidationResult.t()}

Validates an OpenAPI specification without converting it.

Parameters

  • spec: OpenAPI specification as a map

Returns

{:ok, validation_result} on success, {:error, reason} on failure.