Write or paste an OpenAPI 3.0, 3.1 or Swagger 2.0 spec on the left and get live API documentation on the right: endpoints grouped by tag, parameters, request and response schemas with generated example JSON, and a Problems list with clickable line numbers. Your draft is saved automatically in this browser.
Last updated:
Your draft is saved automatically in this browser only (local storage) and is never uploaded. Click an endpoint's Edit link to jump to its YAML. Tab indents by two spaces; press Esc then Tab to leave the editor.
Advertisement
Advertisement
How to use the OpenAPI Editor
Start from a template (the Task Tracker 3.1 example loads first), open your own .yaml/.json file, or paste a spec.
Edit on the left: the documentation on the right refreshes as you type, and problems are highlighted in the gutter.
Insert snippets for a new path, operation, query parameter, schema or security scheme; they are placed in the right section automatically.
Check the Problems tab and click an item to jump to its line; use Edit on any endpoint to find its YAML.
Download the finished spec as YAML or JSON, or copy it to the clipboard.
Anatomy of an OpenAPI document
Every OpenAPI 3 document is built from the same few top-level sections. Knowing where each piece belongs makes the editor's Problems list much easier to act on:
Section
Required?
What goes in it
openapi
Yes
The spec version as a string, e.g. 3.1.0 (Swagger 2.0 uses swagger: "2.0").
info
Yes
title and version (of your API), optional description, contact and license.
servers
No
Base URLs, optionally with {variables} such as an environment or region.
paths
Yes in 3.0, optional in 3.1
Each URL template (/tasks/{taskId}) with its operations: get, post, put, patch, delete…
components
No
Reusable schemas, parameters, responses, requestBodies and securitySchemes, referenced with $ref.
security
No
Default authentication for all operations; operations can override it (use security: [] for public endpoints).
tags
No
Names and descriptions used to group operations in documentation.
Tips for writing specs by hand
Quote status codes and versions: write '200': and version: "1.0". Unquoted, YAML reads them as numbers.
Define schemas once: put models under components/schemas and reference them, so request, response and documentation stay consistent.
Use allOf for "create" vs "read" models: a NewTask schema plus Task = allOf [NewTask, {id, createdAt}], as in the template, avoids duplicating fields.
Give every operation an operationId: code generators use it as the method name, so keep it unique and camelCase.
Mark server-generated fields readOnly (ids, timestamps) so clients know not to send them; the example generator follows the same rule for writeOnly fields.
Describe errors: add 4XX responses or a shared default error response so client developers know what failures look like.
Only need to check an existing file? The OpenAPI Validator gives a full report and a dereferenced download. To browse a finished spec with search and Swagger UI, use the OpenAPI Viewer.
Frequently asked questions
Where is my spec stored?
Only in your browser's local storage on this device, so it is still there when you come back. Nothing is uploaded to a server. Clearing site data or using a private window removes the draft, so download important specs.
Is this the same as Swagger Editor?
It covers the same everyday workflow (edit YAML, see rendered docs and errors side by side) but is a lightweight, independent tool. It does not send test requests to your API; for that, export the spec and use an API client, or try the API Request Tester.
Should I write OpenAPI in YAML or JSON?
Both describe exactly the same document. YAML is easier to read and write by hand and allows comments; JSON is easier to generate and parse in code. The editor converts between them in one click (comments are not carried over to JSON).
Which OpenAPI version should a new API use?
OpenAPI 3.1 is the current version and aligns schemas with JSON Schema 2020-12 (for example type: [string, 'null'] instead of nullable). Use 3.0.3 if your code generator or gateway does not support 3.1 yet; Swagger 2.0 is only for older tooling.
How are the example payloads created?
For each request and response schema the editor builds sample JSON from example, default or enum values when present, and otherwise from the type and format (for instance a date-time string or a UUID). writeOnly properties are left out of examples.
Does it support $ref and allOf?
Yes. Internal references such as #/components/schemas/Task are followed in the preview, allOf schemas are merged into one property list, and oneOf/anyOf alternatives are listed. Recursive schemas are shown once with a recursion marker.
Can I use it offline?
After the page has loaded, editing, preview and validation work without a connection. The YAML parser is loaded from a CDN the first time; JSON specs work even if it cannot load.
Are all the tools on FreeToolCabin tested for quality and accuracy?
Yes! Every tool on our site undergoes automated Q/A testing in real browser environments to ensure high precision, correct output, and zero errors. If you happen to spot a bug or have a suggestion, please contact us at [email protected] and our team will review it right away.