Create specifications using the spec editor

Create and validate OpenAPI Specifications without writing any code using the spec editor.

Access the spec editor

Open an OpenAPI Specification in the spec editor, as described in the following sections:

The following figure shows the specification for the Petstore API open in the spec editor:

As highlighted in the previous figure, the spec editor enables you to:

  • Create your OpenAPI Specification to model your API using JSON or YAML format in the left pane.
  • View auto-generated API documentation in the right pane.
  • Validate your specification against the OpenAPI Specification standard, as you type.
  • Save your OpenAPI Specification or close the spec and cancel your edits.

Help me with JSON and YAML

JSON (JavaScript Object Notation) is a lightweight data interchange format used for representing simple data structures and associative arrays. To learn more, see https://www.json.org.

YAML (YAML Ain't Markup Language) is a data serialization/representation standard that provides a syntax that also provides a syntax that can be mapped to data structures, such as lists, associative arrays, and scalars. To learn more, see https://yaml.org.

Both JSON and YAML are machine readable, but are also easy for humans to read and understand. The following figure compares two short excerpts from the same OpenAPI Specification written using JSON and YAML:

JSON versus YAML

Validate a specification

The spec editor validates your OpenAPI Specification against the OpenAPI Specification standard. As you type, if there are errors in your OpenAPI Specification, the spec editor displays the Error dialog at the top of the right pane and provides more information about the errors and their associated line numbers so you can easily correct them.

Errors

Save a specification

To save an OpenAPI Specification, click Save in the top navigation bar.

If this is the first time that you are saving the specification, you are prompted to enter a filename. If you do not specify a filename, it defaults to Untitled. You can rename it later.

Close a specification

To close an OpenAPI Specification without saving your edits, click Cancel in the top navigation bar. You are returned to the specification list.