How to design request and response schemas in APIKumo for cleaner, self-documenting APIs

Raw JSON responses in API documentation tell readers what an endpoint returns, but they rarely explain why . A field called could be a string, an enum, a boolean disguised as a number — the consumer has no way to know without reading source code or asking you directly. Structured schemas fix this. In APIKumo, the schema editor lets you annotate every request and response shape with field names, types, enums, and worked examples, and those annotations flow straight into your published docs site without any extra writing. This post walks through the full workflow, from opening the editor to shipping documentation your consumers will actually trust. Why raw response blobs aren't enough When a docs page shows only a captured response body, readers are forced to reverse-engineer your API from a single snapshot. A few problems with that approach: - One example, infinite edge cases. The sample you captured probably doesn't show nullable fields, optional keys, or the full range of an enum. - Types are ambiguous. JSON doesn't distinguish between an integer ID and a string ID that happens to contain digits. A schema makes the contract explicit. - Enums go undocumented. If can be , , or , a reader has no way to discover that from a single example. - Docs drift. A pasted blob goes stale the moment the shape changes. A schema you maintain alongside the request stays in sync because it lives in the same workspace. APIKumo's structured schema editor is designed to solve all of these — with as little friction as possible. Opening the schema editor Every saved request in a collection has two schema slots: one for the request body and one for the response . To reach them, open any saved request and switch to the Schema tab alongside Headers, Body, and Pre/Post processors. You'll see two expandable panels — Request Schema and Response Schema — each starting empty. You can build a schema from scratch using the field editor, or paste in an existing JSON example and let the editor infer a baseline structure that you then refine. If you're migrating from an OpenAPI spec or a Postman collection, the imported data already populates these panels wherever schema definitions were present in the source file, so you don't start from zero. Defining fields, types, and enums Each field in the editor has four core properties: | Property | What it does | |---|---| | Name | The exact key as it appears in the JSON payload | | Type | , , , , , , or | | Required | Whether the field must be present in every request or response | | Description | A plain-English explanation surfaced verbatim in the docs | For fields you can additionally specify an enum — a comma-separated list of the only values the API will accept or return. For example, an field might have: The published docs page renders this as a labelled list, so consumers know immediately that is not a valid value and won't build a branch around it. For and types you can nest child fields. An type reveals an Add child field button; an type lets you define the shape of each item. This nesting can go as deep as your payload warrants — a common pattern is a top-level object containing a array of order objects, each with its own nested object. Adding examples that actually help Every field accepts one or more example values . These are distinct from the live response captured when you last sent the request — they're curated illustrations of what a realistic value looks like. Good examples make a material difference to developer experience: - An field with the example is clearer than one with . - A field with tells a reader the format is ISO 8601 UTC without needing a description sentence. - An field with alongside the description "Amount in the smallest currency unit (e.g. cents)" prevents the classic off-by-100 integration bug. Examples you add in the schema editor are composited into a synthetic example payload on the docs page. This is separate from the raw captured response and stays current even if you haven't sent the request recently — making it far more reliable as reference material. How schemas surface in the published docs site Once a collection is published to your site, every saved request becomes a docs page automatically. The schema you defined appears in two places on that page: 1. Parameters and body section — request schema fields are listed with their types, required badges, enum values, and descriptions. Readers can scan the table without needing to construct a trial request. 2. Response section — the response schema appears alongside the latest captured response body. Readers see both the raw snapshot and the annotated contract, so they understand which fields are always present and which are optional. No extra writing, no separate docs tool, no copy-pasting field tables into a Notion page. The schema editor is the documentation authoring step. The Try-it panel on published docs pages also benefits: because the request schema is defined, the panel can show placeholder hints per field rather than an empty body editor, which lowers the barrier for readers to make their first successful call. Keeping schemas in sync with environment variables APIKumo's substitution works in schema example values the same way it works in request URLs and headers. If your environment variable differs between staging and production, any example that references it resolves correctly for the active environment. A common pattern is to store a representative resource ID in an environment variable and reference it in schema examples: When a reader uses the Try-it panel against the staging environment, they see pre-filled rather than a generic placeholder. When you flip to production, the resolved value updates automatically — secrets never leak into the published docs because variable values are resolved at send-time, not stored in the collection. Versioning schema changes with changelog Schemas change. Fields get added, types get tightened, enums grow. APIKumo's versions and changelog feature lets you snapshot a collection at any point, continue editing the next version safely, and surface a diff to readers when you ship. A practical workflow: 1. Snapshot v1 of your collection once the initial schema is stable. 2. Add the new field to the response schema, mark it optional for now. 3. Snapshot v2 and write a one-line changelog entry: "Added optional field to order response." 4. Publish. Readers see the version selector and the changelog entry — no guessing what changed between integrations. This is especially valuable if consumers have built client code against your docs. A visible changelog entry about a new required request field is the difference between a smooth upgrade and a silent 400 error in production. Exporting schemas for other tools The structured schema you build in APIKumo isn't locked in. From your published subdomain you can export: - OpenAPI 3 export — a fully formed spec with entries populated from your field definitions, ready to feed into code generators, gateway validators, or linting pipelines. - Markdown docs export — a flat Markdown file with all schema tables included, suitable for a GitHub wiki or a monorepo folder. - export — a machine-readable representation of your API surface that AI agents and LLM-powered tools can fetch directly from . All three exports are reachable on the same subdomain without auth headers, so CI pipelines and AI agents can fetch them on demand. Putting it all together A well-defined schema is the foundation of every other piece of APIKumo's docs pipeline. It feeds the published docs page, powers the Try-it panel, informs the AI chat assistant on your docs site, and produces valid OpenAPI output — all from the same editor you use to design and test the request itself. The workflow is straightforward: open a saved request, fill in the schema fields with accurate types, a meaningful description, and at least one realistic example value, then publish. Your consumers get field-level documentation, enum constraints, and a synthetic example payload without you writing a single docs paragraph outside the tool. Start with your most-used endpoint, get the schema right, and the rest of the collection follows the same pattern.