---
slug: "pi-openapi-tools"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/gtesei/pi-openapi-tools@main/README.md"
repo: "https://github.com/gtesei/pi-openapi-tools"
source_file: "README.md"
branch: "main"
---
# pi-openapi-tools

![pi-openapi-tools demo](https://github.com/gtesei/pi-openapi-tools/raw/HEAD/demopi.gif)

[Pi](https://github.com/earendil-works/pi) extension that generates LLM tools from any OpenAPI/Swagger URL. The examples below use the `papi` tool-name prefix.

## Install

```bash
pi install npm:pi-openapi-tools
```

## Install (development)

```bash
# load directly from local clone
pi -e /absolute/path/to/pi-openapi-tools/extensions/index.ts
```

## Usage

### Tutorials

- [Swagger Petstore walkthrough](https://github.com/gtesei/pi-openapi-tools/blob/HEAD/docs/swagger-petstore-tutorial.md)
  - Includes matching automated simulation test: `tests/swagger-petstore-tutorial.test.ts`
- [Pi prompt/context sources (Pi-level)](https://github.com/gtesei/pi-openapi-tools/blob/HEAD/docs/prompt-context-pi-level.md)
  - Explains where system prompt/context comes from and how this extension is injected via tools

### Command

```
Usage:
  /swagger-tools <openapi-url> [options]

Options:
  --base-url <url>     Override the base URL used for requests
  --auth-header <val>  Authorization header value (e.g. 'Bearer ...')
  --prefix <name>      Prefix generated tool names
  --tags <a,b,c>       Only include operations with these tags
  --help, -h           Show this help

Manage tools:
  /swagger-tools:list
  /swagger-tools:list-prefixes
  /swagger-tools:describe <toolName>
  /swagger-tools:remove-prefix <prefix>

Examples:
  /swagger-tools http://localhost:8080/swagger/json --base-url http://localhost:8080 --prefix papi
  /swagger-tools https://api.example.com/openapi.json --base-url https://api.example.com --prefix papi
```

With `--prefix papi`, generated tools are named like `papi_posttoken` and `papi_postv2documentsearches`.

### List tools

```
/swagger-tools:list
```

### List registered prefixes

```
/swagger-tools:list-prefixes
```

Shows all currently active prefixes.
Registrations are additive by prefix: generating a new prefix keeps existing prefixes,
and re-generating an existing prefix replaces only that prefix’s tools.
If tools were generated without `--prefix`, it reports that no prefix is registered.

### Remove tools by prefix

```
/swagger-tools:remove-prefix papi
# or
/swagger-tools:remove-prefix --prefix papi
```

Removes all currently generated tools whose names match the prefix (exact match or `<prefix>_...`). Removed tools are replaced with a non-executable stub, and you can re-create them by running `/swagger-tools` again.

### Describe a tool

```
/swagger-tools:describe papi_postv2documentsearches
```

### Auth token helper

```
/swagger-tools:auth --client-id <client-id> --client-secret <client-secret>
/swagger-tools:auth --tool papi_posttoken --client-id <client-id> --client-secret <client-secret>
/swagger-tools:auth --base-url http://localhost:8080 --client-id <client-id> --client-secret <client-secret>
/swagger-tools:auth:clear
```

The auth helper searches for a `POST` endpoint whose path or description contains
one of `token`, `oauth`, `openid`, or `oidc`. Use `--tool` to override the
selection. For the PAPI spec, successful auth reports `Auth token stored for papi_posttoken.` Stored auth is scoped to the current base URL and is cleared when you
switch APIs.

### Tool

Call the `generate_swagger_tools` tool with:

```json
{
  "swaggerUrl": "https://api.example.com/openapi.json",
  "baseUrl": "https://api.example.com",
  "authHeader": "Bearer <token>",
  "prefix": "papi",
  "tags": ["Text", "Documents"]
}
```

## Notes

- Tools are generated dynamically at runtime using the OpenAPI/Swagger `paths` definitions.
- If `baseUrl` is omitted, the extension tries to infer it from the spec.
- Request bodies follow the OpenAPI content type when one is declared and fall
  back to JSON when no request body metadata is available.

## Development

Clone and run Pi with the extension:

```bash
pi -e /path/to/pi-openapi-tools/extensions/index.ts
```

Run tests:

```bash
npm install
npm test
# or
bun run test

# tutorial simulation only
node --experimental-strip-types --test tests/swagger-petstore-tutorial.test.ts
```

## License

MIT