Import Openapi Microservice

CRITICAL: This skill does NOT define the shape of generated code. It delegates every feature to the add-microservice, add-function, add-web, and add-config skills, the single source of truth for code shape. This skill only scaffolds the microservice, produces the specs file, picks endpoints, and fills the one-line delegation body.

CRITICAL: The microservice is a faithful one-for-one delegator. Do NOT reshape the remote API: never split a request body into separate arguments, rename routes, or collapse status codes. Body-bearing operations use the magic HTTP arguments so the microservice is byte-transparent to its callers.

CRITICAL: openapispecs.json lives in the microservice's directory and is tracked in source control (never git-ignored). It is the durable record of the remote API. Re-running this skill imports more endpoints from the present specs without re-fetching, and skips endpoints already scaffolded.

Workflow

Copy this checklist and track your progress:

- [ ] Step 1: Locate or scaffold the microservice
- [ ] Step 2: Acquire the OpenAPI document
- [ ] Step 3: Generate openapispecs.json
- [ ] Step 4: Add the base-URL and credential configs
- [ ] Step 5: Add the shared request helpers (once)
- [ ] Step 6: Select which endpoints to import
- [ ] Step 7: Generate the complex types
- [ ] Step 8: Declare the endpoints in definition.go
- [ ] Step 9: Generate the boilerplate
- [ ] Step 10: Implement the handler bodies
- [ ] Step 11: Wire the HTTP egress proxy into the app
- [ ] Step 12: Housekeeping

The placeholders myservice, MyService, myserviceapi stand for the microservice being generated.

Step 1: Locate or Scaffold the Microservice

If a delegator for this API already exists, its openapispecs.json and local CLAUDE.md record what is already imported. If the user only wants more endpoints, skip to Step 6 (the specs are already present; do not re-fetch unless the user wants a newer version of the document).

Otherwise follow the add-microservice skill. Name the microservice after the remote API itself (petstore, not petstorewrap/petstoreproxy/petstoreclient): in the mesh this microservice is that API's representation, and a suffix leaks an implementation detail into a hostname every caller sees. "Delegator" describes what it does, never what it is named. Give it a one-line description (MyService delegates to the Petstore API.); Step 3 appends the API's own overview.

Step 2: Acquire the OpenAPI Document

Place the document in the microservice directory as myservice/openapi.src:

• By URL: curl -fsSL '<url>' -o myservice/openapi.src. Remember the URL for Step 3.
• Pasted: write the pasted content verbatim to myservice/openapi.src.

Do not hand-edit it. JSON and YAML are both accepted.

Step 3: Generate openapispecs.json

go run github.com/microbus-io/fabric/cmd/genopenapispecs -base-url 'ORIGIN' < myservice/openapi.src > myservice/openapispecs.json
rm myservice/openapi.src

The tool is a pure offline filter (stdin to stdout; never touches the network).

-base-url is optional and defaults to the document's first servers URL. Real documents often declare a relative server (e.g. /api/v3); the tool then warns on stderr. Set -base-url to that URL's origin (scheme://host) joined with the relative server path, e.g. https://petstore3.swagger.io/api/v3. If the document was pasted with no absolute server and you have no URL, ask the user for the base URL.

The specs file has info, remote{baseURL,security}, types{} (raw JSON Schema keyed by name), and endpoints[] (each with name, feature, method, route, summary, description, params, requestBody, response). feature is function (JSON or empty body) or web (non-JSON body); trust it unless an endpoint is obviously misclassified.

If the specs info.description is non-empty, append it to the Service godoc and svc.SetDescription after the one-line summary from Step 1, separated by a blank line so it renders as a second godoc paragraph.

Step 4: Add the Base-URL and Credential Configs

Follow the add-config skill:

1. RemoteBaseURL: default remote.baseURL from the specs, validation url.
2. Credential, secret: true, no default. Only when remote.security is present. Name it for the scheme: APIKey (apiKey), BearerToken (http-bearer/oauth2), or BasicAuth (http-basic, value is the user:password pair).

Step 5: Add the Shared Request Helpers (Once)

Add these helpers to service.go exactly once, not per endpoint. They are the only delegation logic; every handler becomes a single call into them. Add imports bytes, context, encoding/json, io, net/http, strings, errors, github.com/microbus-io/fabric/httpx, and the httpegressapi package.

// remoteURL joins the configured base with an operation path, tolerating a configured base that
// has (or lacks) a trailing slash. path must start with "/".
func (svc *Service) remoteURL(path string) string {
	return strings.TrimRight(svc.RemoteBaseURL(), "/") + path
}

// authenticate injects the remote credential per the specs remote.security. Write its body once,
// keeping only the line for this API's scheme:
//   apiKey header -> req.Header.Set("<name>", svc.APIKey())
//   apiKey query  -> q := req.URL.Query(); q.Set("<name>", svc.APIKey()); req.URL.RawQuery = q.Encode()
//   http-bearer/oauth2 -> req.Header.Set("Authorization", "Bearer "+svc.BearerToken())
//   http-basic -> u, p, _ := strings.Cut(svc.BasicAuth(), ":"); req.SetBasicAuth(u, p)
func (svc *Service) authenticate(req *http.Request) {
	req.Header.Set("Authorization", "Bearer "+svc.BearerToken())
}

// makeFunctionRequest forwards a typed call to the remote API: it sends method+url with an optional
// JSON-encoded in body, decodes a JSON response into out when out is non-nil, and returns the remote
// status code unchanged.
func (svc *Service) makeFunctionRequest(ctx context.Context, method, rawURL string, in, out any) (status int, err error) {
	var body io.Reader
	if in != nil {
		b, err := json.Marshal(in)
		if err != nil {
			return 0, errors.Trace(err)
		}
		body = bytes.NewReader(b)
	}
	req, err := http.NewRequest(method, rawURL, body)
	if err != nil {
		return 0, errors.Trace(err)
	}
	if in != nil {
		req.Header.Set("Content-Type", "application/json")
	}
	svc.authenticate(req)
	resp, err := httpegressapi.NewClient(svc).Do(ctx, req)
	if err != nil {
		return 0, errors.Trace(err)
	}
	defer resp.Body.Close()
	if out != nil {
		err = json.NewDecoder(resp.Body).Decode(out)
		if err != nil {
			return resp.StatusCode, errors.Trace(err)
		}
	}
	return resp.StatusCode, nil
}

// makeWebRequest forwards a raw web call (caller's query string and body included) and relays the
// remote response to w unchanged. httpx.Copy transfers the body buffer without copying its bytes.
func (svc *Service) makeWebRequest(w http.ResponseWriter, r *http.Request, method, rawURL string) (err error) {
	req, err := http.NewRequest(method, rawURL, r.Body)
	if err != nil {
		return errors.Trace(err)
	}
	req.URL.RawQuery = r.URL.RawQuery
	req.Header = r.Header.Clone()
	svc.authenticate(req)
	resp, err := httpegressapi.NewClient(svc).Do(r.Context(), req)
	if err != nil {
		return errors.Trace(err)
	}
	defer resp.Body.Close()
	return errors.Trace(httpx.Copy(w, resp))
}

The status code is passed through unchanged. Do not add retries, caching, or reshaping; cross-cutting concerns belong in the caller.

Step 6: Select Which Endpoints to Import

Read the candidate endpoints from myservice/openapispecs.json (endpoints[]; each has name, feature, method, route, summary). This is the entry point when Step 1 sent you straight here for an existing delegator. Large APIs have hundreds of endpoints; import only the curated subset the project needs.

• Agent-relevant (default mid-task): select the endpoints the task requires, list them to the user with one-line justifications, and proceed. More can be added later from the same specs.
• Interactive (default for a bare "import this API"): present the endpoints grouped by route with method, name, summary and ask the user to choose. Offer "all" for small APIs.

Skip endpoints already scaffolded (their // MARKER comment, keyed by the endpoint name, is in myserviceapi/definition.go); re-import is additive. Record the imported names under a ## Imported Endpoints heading in the local CLAUDE.md.

Step 7: Generate the Complex Types

For every type a selected endpoint references via $ref: 'Name' in its params, requestBody, or response, define a Go struct from types['Name'] in the specs (a $ref value is the bare type name and keys the types map directly; nested $refs inside a type schema work the same way). Follow the add-function skill's "Define Complex Types" conventions (one file per type under myserviceapi/, json camelCase omitzero, jsonschema_description:"..." from the schema's description) for the Go mapping. For oneOf/anyOf/allOf or free-form objects with no properties, fall back to json.RawMessage and note the fallback in the type's godoc.