From cfe98a62b6776d00dc1f6a6e02d790d6b9bc2794 Mon Sep 17 00:00:00 2001
From: David Gageot <david.gageot@docker.com>
Date: Fri, 10 Apr 2026 14:46:59 +0200
Subject: [PATCH] docs: add documentation for OpenAPI toolset

Assisted-By: docker-agent
---
 docs/_data/nav.yml          |  2 ++
 docs/tools/openapi/index.md | 58 +++++++++++++++++++++++++++++++++++++
 2 files changed, 60 insertions(+)
 create mode 100644 docs/tools/openapi/index.md

diff --git a/docs/_data/nav.yml b/docs/_data/nav.yml
index b48b0b14b..d3234f2fa 100644
--- a/docs/_data/nav.yml
+++ b/docs/_data/nav.yml
@@ -69,6 +69,8 @@
       url: /tools/background-agents/
     - title: Handoff
       url: /tools/handoff/
+    - title: OpenAPI
+      url: /tools/openapi/
     - title: A2A
       url: /tools/a2a/
 
diff --git a/docs/tools/openapi/index.md b/docs/tools/openapi/index.md
new file mode 100644
index 000000000..9ce6e111e
--- /dev/null
+++ b/docs/tools/openapi/index.md
@@ -0,0 +1,58 @@
+---
+title: "OpenAPI Tool"
+description: "Automatically generate tools from an OpenAPI specification."
+permalink: /tools/openapi/
+---
+
+# OpenAPI Tool
+
+_Automatically generate tools from an OpenAPI specification._
+
+## Overview
+
+The OpenAPI tool fetches an OpenAPI 3.x specification from a URL and creates one tool per API operation. Each endpoint's parameters, request body, and description are translated into a callable tool that the agent can invoke directly.
+
+## Configuration
+
+```yaml
+toolsets:
+  - type: openapi
+    url: "https://petstore3.swagger.io/api/v3/openapi.json"
+```
+
+### With custom headers
+
+Pass custom headers to every HTTP request made by the generated tools (for example, for authentication):
+
+```yaml
+toolsets:
+  - type: openapi
+    url: "https://api.example.com/openapi.json"
+    headers:
+      Authorization: "Bearer ${env.API_TOKEN}"
+      X-Custom-Header: "my-value"
+```
+
+## Properties
+
+| Property  | Type              | Required | Description                                                                 |
+| --------- | ----------------- | -------- | --------------------------------------------------------------------------- |
+| `url`     | string            | ✓        | URL of the OpenAPI specification (JSON format)                              |
+| `headers` | map[string]string |          | Custom HTTP headers sent with every request. Values support `${env.VAR}` and `${headers.NAME}` placeholders. |
+
+## How it works
+
+1. The spec is fetched from the configured `url` at startup.
+2. Each operation (GET, POST, PUT, …) becomes a separate tool named after its `operationId` (or `method_path` when no `operationId` is set).
+3. Path and query parameters are exposed as tool parameters. Request body properties are prefixed with `body_`.
+4. Read-only operations (GET, HEAD, OPTIONS) are annotated accordingly.
+5. Responses are returned as text; errors include the HTTP status code.
+
+## Limits
+
+- The OpenAPI spec must be **10 MB or less**.
+- Individual API responses are truncated at **1 MB**.
+
+## Example
+
+See the full [Pet Store example](https://github.com/docker/docker-agent/blob/main/examples/openapi-petstore.yaml) for a working agent configuration.