DEV Community

isaac
isaac

Posted on

Turning OpenAPI Specs into Runtime LLM Tools in Pi

I built pi-openapi-tools — a Pi extension that ingests 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 calling generated tools.

Why I built this

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

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

That friction slows experimentation and makes agent tooling brittle.

I wanted a runtime-first workflow:

spec → generated tools → live API calls

What the extension does

Given an OpenAPI or Swagger 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 declared media/content type
  • handles path, query, and header parameters
  • 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 get generated tools like:

  • pet_getstoreorderbyid
  • pet_postuser
  • etc.

Implementation details that mattered

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

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

  • No unregister API in Pi? Stub instead.
    Removed tools become non-executable guidance stubs rather than silently disappearing.

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

Docs + walkthrough

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

  • 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)