Skip to main content

​
Response Documentation, OpenAPI-Complete

Endpoints can now document their responses — per status, with JSON example bodies — and the model matches the OpenAPI Responses Object exactly:
  • Every response key OpenAPI allows: a concrete status code (200), an uppercase range (4XX) or default. The Studio editor accepts all three, the API page renders them, and the OpenAPI import no longer drops range or default entries.
  • Named examples: one status can carry several example bodies — each with a name and an optional summary — to document different situations: a match versus an empty result, two different causes of a 400. The API page renders every example under its status.
  • Round-trip fidelity: the OpenAPI export emits a single anonymous example as the singular example (what tooling renders most reliably) and anything richer as the named examples map; the import collects every named application/json example instead of only the first.

​
Capture Live Responses as Examples

Writing example bodies by hand is the tedious part of good documentation — so now you don’t have to:
  • Capture from live request (Studio → endpoint → Responses): send a real request through the gateway, prefilled with your documented example parameters, and save the live response as an example. Need a 400 example? Break a parameter on purpose and capture that.
  • Save as example (API page playground): as the API’s owner, every completed playground request gains a Save as example button that files the response body into your documentation.
  • Generate example responses (Studio → Endpoints): bulk-capture across every endpoint whose parameters are documented. The estimated credit cost is shown before anything is sent, results are reviewed before anything is saved, and only clean 2xx responses are pre-selected. Endpoints that can’t be captured are listed with what’s missing — doubling as a documentation to-do list.
Captured bodies are real responses, so a review step guards what goes public:
  • Trim arrays to first 2 items cuts a 200-element list down to a readable example in one click.
  • Fields that look like credentials or personal data (API keys, tokens, e-mail addresses) are flagged for redaction before publishing.
  • Responses produced by the gateway itself — auth, billing and quota errors — are detected and never auto-saved. Those are documented centrally in gateway-generated responses, which the playground now links.
Capture requests go through the gateway like any consumer request and are billed as such — so what you capture is exactly what your consumers will see.