OpenAPI-Delegating Microservices
To reach a third-party REST API from inside the mesh, Microbus represents it as a normal microservice that delegates one-for-one to the remote API. A dedicated coding agent skill reads the API’s OpenAPI (Swagger) document and scaffolds that microservice — typed endpoints, configuration, and the request plumbing — so callers invoke the remote API the same way they invoke any other Microbus endpoint, with mesh authentication, tracing, and ACLs applied on the way in.
Scaffold a Delegating Microservice
Point your coding agent at the API’s OpenAPI document, by URL or pasted JSON/YAML:
The microservice is named after the remote API itself (petstore, not petstoreproxy) — in the mesh it is that API’s representation. The agent fetches the document, runs it through the genopenapispecs tool to produce a normalized openapispecs.json, adds the base-URL and credential configuration, and generates one endpoint per imported operation. Outbound HTTP goes through the HTTP egress proxy, which the agent wires into the application if it isn’t already present.
petstore/
├── petstoreapi/
│ ├── definition.go # Typed endpoint definitions (the API's source of truth)
│ └── client.go # Generated client stubs for upstream callers
├── openapispecs.json # Normalized record of the remote API (source-controlled)
├── service.go # Shared request helpers + one delegating handler per endpoint
├── manifest.yaml
└── CLAUDE.md # Records which endpoints have been importedFaithful One-for-One Delegation
The generated microservice is a byte-transparent delegator. It does not reshape the remote API: routes, request bodies, and status codes pass through unchanged, and the remote status code is returned to the caller as-is. There is no retry, caching, or response rewriting in the generated code — those are cross-cutting concerns that belong in the caller, not baked into the API’s representation. This keeps the microservice a predictable stand-in for the remote API and makes it safe to regenerate.
JSON request/response operations become typed function endpoints; operations with non-JSON bodies (file uploads, streams) become web endpoints that relay the raw request and response.
Import Endpoints Incrementally
Large APIs have hundreds of operations; you rarely want all of them. The skill imports only the subset you ask for — either the specific endpoints a task needs, or an interactive selection grouped by route. The openapispecs.json file is the durable, source-controlled record of the remote API. Re-running the skill imports more endpoints from the same specs without re-fetching the document, and skips operations already scaffolded, so importing a new endpoint later is an additive, conflict-free step.
Credentials and Security
If the OpenAPI document declares a security scheme, the skill adds a secret configuration property for the credential (APIKey, BearerToken, or BasicAuth) and injects it into each outbound request server-side. The remote credential lives in the microservice’s config and is never exposed to callers.
Because the microservice wields a stored credential on the caller’s behalf, each endpoint is a potential confused deputy: an externally reachable endpoint with no required claims would let any outside caller spend the operator’s credential. The skill therefore defaults each generated endpoint to closed — gated by requiredClaims and/or placed on an internal-only port — and leaves it open only when the remote operation is genuinely public. Review the generated requiredClaims against who should actually be allowed to call each endpoint.
Further Reading
- Petstore example - a worked output of this skill: three endpoints imported from the public Swagger Petstore document (one typed function, one with a path argument, one raw web upload), shown with their generated delegation code.
- Agent Skills - how skills drive the coding agent.
genopenapispecs- the offline tool that normalizes an OpenAPI document intoopenapispecs.json.- HTTP Egress - the proxy that carries the delegated outbound calls.