API Reference Pages

API Reference Pages

Zingasolve can document your own API right alongside the rest of your docs.
You organize endpoints into categories, either import an OpenAPI/Swagger spec or
author them by hand, and publish an interactive reference where readers can send
real requests from the browser.

Creating an API reference

In the Zingasolve portal, open API reference and add an API. Each API
reference has:

• A title and optional description and version (for example v1).
• A server base URL — the address requests are sent to, such as
  https://api.acme.com/v1. The in-browser Trial will only ever call the
  server(s) you configure here.
• An auth scheme that tells readers (and the Trial) how to authenticate:

• A status of draft or published.

Importing an OpenAPI / Swagger spec

The fastest way to build a reference is to import a spec. Open the API's detail
panel and either paste the OpenAPI JSON or YAML or provide a URL to it
(for example https://api.acme.com/openapi.json), then import. Both OpenAPI 3.x
and Swagger 2.0 are supported.

The import builds your reference automatically:

• Servers and auth are read from the spec.
• Categories are created from the spec's tags.
• Endpoints are created from each path and method, carrying their summary,
  description, parameters, request body, and documented responses.
• The API's version and description are filled in from the spec's info.

Import is idempotent: re-importing replaces the reference's categories and
endpoints with the current spec, so keeping your docs in sync is just a
re-import. (Re-importing does replace those endpoints, so any manual tweaks to
them are overwritten — re-import from an updated spec, then adjust.)

Organizing endpoints

Endpoints are grouped into categories (the equivalent of OpenAPI tags), and
each endpoint records:

• Its method and path (for example GET /orders/{id}).
• A summary and longer description.
• Parameters — path, query, or header — with type, whether required, and an
  example.
• A request body shape and example, where applicable.
• Documented responses by status code.
• Whether authentication is required and whether it is deprecated.

You can remove individual endpoints you don't want to publish.

The in-browser Trial (try-it)

Published API references render on your docs site with a Trial console so
readers can send requests without leaving the page. They fill in parameters and
a body, supply their own token if the API needs auth, and get the live response
back inline.

The Trial is designed to be safe:

• Requests go only to the server URL(s) you configured on the reference —
  arbitrary hosts are rejected.
• Requests are sent server-side by Zingasolve, so browser cross-origin (CORS)
  restrictions don't get in the way and the reader's token never touches
  third-party scripts.
• There are sensible timeouts, a response-size cap, and rate limiting to keep
  the console well-behaved.

Publishing

Set the reference to published when it's ready. It then appears on your docs
micro-site, linked from the site's footer, and readers can browse the categories,
read each endpoint's details, and use the Trial. Draft references stay hidden
until you publish. See Publishing & the Docs Site for how the micro-site and
custom domains work.

Tips

• Point the server base URL at a sandbox or test environment if you want
  readers to experiment freely without touching production data.
• Keep an OpenAPI spec as your source of truth and re-import after each API
  change so the reference and the Trial never drift from the real API.
• Use clear tags in your spec — they become the categories readers navigate by.