This library exposes an AI tool that can read an OpenAPI 3 specification and provide high‑level information about available endpoints, detailed endpoint descriptions, schemas and simple search capabilities. Local specification files are always accessed through a filesystem sandbox defined by configuration.

Installation

composer require adachsoft/open-api-reader-tool

This will also install its runtime dependencies:

adachsoft/open-api-reader – low‑level OpenAPI 3 parser
adachsoft/ai-tool-call – SPI for tool definition and execution
guzzlehttp/guzzle – HTTP client for fetching remote OpenAPI documents
adachsoft/sandbox-contracts – filesystem sandbox contracts used to scope file access

Configuration

The tool is created via OpenApiToolFactory and expects a configuration map (ConfigMap) that contains at least the base_path key:

use AdachSoft\AiToolCall\SPI\Collection\ConfigMap;
use AdachSoft\OpenApiReaderTool\OpenApiToolFactory;

$factory = new OpenApiToolFactory();

$config = new ConfigMap([
    'base_path' => __DIR__ . '/specs', // sandbox root for local OpenAPI files
]);

$tool = $factory->create($config);

The base_path value is used to build a sandbox (SandboxPath) coming from adachsoft/sandbox-contracts. Every local file path passed to the tool is resolved within this sandbox; attempts to escape it (e.g. using ..) are rejected.

Tool definition

The exported tool is named openapi_reader and exposes one required parameter action plus a set of optional parameters depending on the chosen action.

Parameters

spec_path_or_url (string, optional)
- Path to a local OpenAPI file inside the sandbox base_path, or an absolute URL to an OpenAPI document.
action (string, required)
- One of:
  - list_endpoints – list endpoints in a paginated way
  - endpoint_details – show details for a specific endpoint
  - schema – fetch a schema definition from components
  - search – perform a simple text search over endpoints
page (integer, optional)
- Page number for list_endpoints (default is 1).
limit (integer, optional)
- Page size for list_endpoints (default is 10, maximum is 100).
path (string, optional)
- OpenAPI path of the endpoint (e.g. /users/{id}), used with endpoint_details.
method (string, optional)
- HTTP method of the endpoint (e.g. GET, POST), used with endpoint_details.
schema_name (string, optional)
- Name of the schema in OpenAPI components, used with schema.
query (string, optional)
- Free‑text search query, used with search.

Basic usage example

The exact integration depends on how you wire tools in your AI orchestration. Below is a minimal, framework‑agnostic example of a single tool call:

use AdachSoft\AiToolCall\SPI\Collection\KeyValueMap;
use AdachSoft\AiToolCall\SPI\Dto\ToolCallRequestDto;
use AdachSoft\OpenApiReaderTool\OpenApiTool;
use AdachSoft\OpenApiReaderTool\OpenApiToolFactory;

$factory = new OpenApiToolFactory();
$tool = $factory->create(new ConfigMap([
    'base_path' => __DIR__ . '/specs',
]));

$request = new ToolCallRequestDto(
    'openapi_reader',
    new KeyValueMap([
        'spec_path_or_url' => 'openapi.yaml',
        'action' => 'list_endpoints',
        'page' => 1,
        'limit' => 10,
    ]),
);

$result = $tool->callTool($request);

// $result->result is a KeyValueMap with key "data" holding the returned array
$endpoints = $result->result->get('data');