# `ExUtcp.OpenApiConverter`
[🔗](https://github.com/universal-tool-calling-protocol/elixir-utcp/blob/main/lib/ex_utcp/openapi_converter.ex#L1)

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"
    })

# `convert`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*