pi-openapi-tools

Pi extension that generates LLM tools from any OpenAPI/Swagger URL. The examples below use the papi tool-name prefix.

Install

pi install npm:pi-openapi-tools

Install (development)

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

Usage

Tutorials

• Swagger Petstore walkthrough
  • Includes matching automated simulation test: tests/swagger-petstore-tutorial.test.ts
• Pi prompt/context sources (Pi-level)
  • 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:

{
  "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:

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

Run tests:

npm install
npm test
# or
bun run test

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

License

MIT