Swagger Editor for OpenAPI

How to use the editor

1. Start from something. The editor opens with a small sample API. Replace it by pasting your own document, or use Open file for a .yaml or .json file. JSON is read as it is; there is no need to convert first.
2. Edit on the left, read on the right. The documentation redraws a moment after you stop typing. Each operation opens to show its parameters, request body, responses and the schemas behind them, with every $ref followed for you.
3. Fix what is listed. Problems appear above the documentation with a line number, and the same lines are marked in the margin of the editor. Click a problem to jump to it.
4. Try an operation. Every operation ends with a cURL command built from its path, required parameters, security scheme and an example body. Open in API tester loads the same request into the request console, ready to send.
5. Take it away. Download saves the document as openapi.yaml or openapi.json. The draft also stays in this browser, so closing the tab does not lose it.

What the editor checks

Two kinds of mistake stop an OpenAPI document from working. The first is in the YAML or JSON itself, and the second is in what it describes. The editor reports both, with the line.

Syntax

Structure

• The version line. openapi: 3.0 and swagger: 2.0 are numbers to YAML, not text. Write openapi: 3.0.3 and swagger: "2.0". The same goes for info.version: 1.0, which needs quotes.
• Required fields: info.title, info.version, paths, a description on every response, responses on every operation (optional from OpenAPI 3.1), name and in on every parameter.
• Path parameters. Every {name} in a path must be declared as a parameter with in: path and required: true, and every declared path parameter must appear in the path. Two paths that differ only in a parameter name are reported, as requests cannot be told apart.
• References. Every $ref that starts with #/ must point at something that exists. Names are case-sensitive, and a Swagger 2.0 style #/definitions/Pet in an OpenAPI 3 document is called out as such.
• Fields in the wrong place or version: responses directly under a path, GET in capitals, definitions or host in OpenAPI 3, requestBody or components in Swagger 2.0, type beside a parameter where OpenAPI 3 wants it inside schema.
• Schemas: a type that does not exist, such as int or datetime; an array with no items; required: true on a property, where a schema wants a list of names on the parent object.
• Names that must match up: duplicate operationId values, duplicate parameters and tags, a security requirement naming a scheme that is not defined, a server URL variable with no definition.

What it does not check

These are structural checks, chosen because they are the mistakes that stop documentation generators, code generators and gateways from reading a description. They are not a full validation against the OpenAPI specification. The editor does not verify every field of every object, does not check examples against their schemas, and does not fetch or follow references to other files or URLs; it counts those and says so. No errors found means none of these checks failed, not that the document is certified valid. Before publishing an API description, run it through the validator or linter your toolchain uses.

Swagger or OpenAPI?

They are the same format at different ages. The format began as the Swagger specification. Version 2.0 is the last to carry that name; when the specification was handed to the OpenAPI Initiative it was renamed, and version 3.0 onward is OpenAPI. "Swagger" now properly refers to the family of tools SmartBear builds around the format, Swagger Editor and Swagger UI among them, although plenty of people still say "the Swagger file" for any OpenAPI document. The Swagger alternative page separates those tools from one another.

OpenAPI 3.1 brought the schema language into line with JSON Schema, which is why nullable: true from 3.0 becomes type: [string, "null"], and it added webhooks for requests your API sends, which are covered in the webhook guide. The editor applies the rules of whichever version the first line declares; documents declaring a later 3.x version are read with the 3.1 rules. It does not convert a document from one version to another.

YAML or JSON?

An OpenAPI document may be written in either, and the two say exactly the same thing. YAML is the usual choice for writing by hand, since it is shorter and allows comments; JSON is what programs prefer to produce and consume. Convert to JSON and Convert to YAML switch the whole document over, and the result is read back and compared before it replaces your text.

Three things about YAML catch people out in API descriptions:

• Unquoted values are typed. 1.0 is a number, true is a boolean and an empty value is null. A version, a postcode or a phone number wants quotes.
• Response codes are written in quotes, as "200":. The specification asks for this so that the same document means the same thing in YAML and in JSON. The YAML this editor writes follows that convention, and quotes words such as yes and no that older YAML readers take for booleans.
• Long text belongs in a block. A description that runs over several lines, or that contains a colon, is safest after a |, with the text indented on the lines beneath. Descriptions may contain Markdown; this editor shows them as plain text, and the Markdown preview renders one.

Converting loses YAML comments, because JSON has nowhere to put them, and expands anchors and aliases into the content they stand for. For a file that is not an API description, the YAML to JSON converter does the same job without the OpenAPI checks.

From description to request

A description is a claim about how an API behaves, and the quickest way to test the claim is to make the call. Open any operation and the editor shows the request it describes:

curl -X POST 'https://api.bookshop.example/v1/books' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "title": "The Left Hand of Darkness",
  "author": "Ursula K. Le Guin",
  "published": "2026-01-01",
  "price": 9.99,
  "tags": [
    "string"
  ]
}'

The URL comes from the selected server and the path. Required query and header parameters are included, and optional ones are left out. The credential is a placeholder shaped by the security scheme: a bearer token, an API key header, or basic auth. The body is the example from the document when there is one, and otherwise a value built from the schema, with read-only properties left out.

Open in API tester carries that request to the console on the home page, where you replace the placeholders and send it. If the response does not match what the document promises — a 422 for a body the schema allows, a field the schema does not mention — one of the two is wrong, and you now know which line to look at. The REST API testing guide covers what else to check, and the cURL converter turns the command into Python, JavaScript or PHP.

Frequently asked questions

Related tools and reference