DEV Community

Gino Tesei
Gino Tesei

Posted on

Turning OpenAPI Specs into Runtime LLM Tools in Pi

I built pi-openapi-tools — a Pi extension that reads an OpenAPI/Swagger spec and dynamically registers one callable tool per API operation.

Instead of hand-writing wrappers for every endpoint, you point Pi at a spec URL and immediately start using generated tools.

Why I built this

Most API-agent integrations still require too much manual glue code:

  • mapping endpoints to functions
  • defining parameter schemas
  • maintaining naming consistency
  • wiring auth/token handling
  • repeating the process for every API

That slows experimentation and makes agent tooling fragile.

I wanted a runtime-first workflow:

spec → generated tools → live API calls

What the extension does

Given an OpenAPI or Swagger spec URL, pi-openapi-tools:

  • Generates one Pi tool per operation
  • Supports Swagger 2.0 and OpenAPI 3.x
  • Builds structured parameter schemas automatically
  • Resolves request bodies by media/content type
  • Handles path, query, and header params
  • Adds slash commands for managing generated toolsets

It also includes:

  • prefix-scoped registrations (/swagger-tools:list-prefixes)
  • prefix cleanup (/swagger-tools:remove-prefix)
  • tool inspection (/swagger-tools:describe)
  • token/auth helpers (/swagger-tools:auth)

60-second quickstart

Install:

pi install npm:pi-openapi-tools
Enter fullscreen mode Exit fullscreen mode

Generate tools from Petstore:

/swagger-tools https://petstore.swagger.io/v2/swagger.json --prefix pet
/swagger-tools:list
Enter fullscreen mode Exit fullscreen mode

You’ll immediately get generated tools such as:

  • pet_getstoreorderbyid
  • pet_postuser
  • etc.

A few implementation details mattered a lot in practice:

  • Prefix-scoped additive registration
    Multiple API toolsets can coexist cleanly.

  • Stable naming + dedupe
    Generated names are sanitized and collision-safe.

  • No unregister support in Pi? Stub instead.
    Removed tools become non-executable guidance stubs instead of silently disappearing.

  • Content-type-aware serialization
    Request body handling follows declared spec media types (JSON, form-data, urlencoded, text, etc).

I also added a full walkthrough + simulation test:

If you try it on large or messy specs, I’d especially love feedback on:

  • operation naming ergonomics
  • auth edge cases
  • request body/media handling
  • discoverability in very large APIs

If this is useful, feel free to star the repo and share your API use case.

Top comments (0)