Edit your API specification

Spec Hub is available with Postman Enterprise plans.

Edit your specification to update the structure and design of your API. Navigate your specification using the outline in the sidebar and the command palette to find and jump to specific sections. You can add new sections using snippets to add pre-formatted blocks that you can fill out. You can also generate a schema from a JSON request or response body, and add the schema directly to your specification.

As you edit your specification, Postman offers autocomplete suggestions for properties and valid values. Postman also identifies syntax errors, such as wrong data types and nesting, and shows details about the errors so you can correct them.

Postman also displays a live preview of your API's documentation in the right sidebar as you edit your specification.

Navigate your specification

Your specification defines the structure of your API. You can navigate your specification from the outline in the sidebar. You can also navigate your specification using the command palette to jump to specific sections.

The sidebar displays an outline of your API specification. Use the arrows to expand or collapse sections. Select a section in the outline to jump to it in the specification. New sections appear in the outline as you add them to your specification.

To jump to a referenced component, hover over a #ref component and select the component while selecting ⌘ or Ctrl.

In the upper right are options to beautify the content, wrap text, copy the specification, and search. When you finish editing your specification, select Save.

If you generated a collection from an OpenAPI 3.0 specification, make sure to update the collection once you're done making changes.

Navigate using the command palette

Find items in your specification and jump to them using the command palette. To show the command palette, select View Command Palette in the upper right. You can also select ⌘+Shift+O or Ctrl+Shift+O.

In the command palette, select an item in the list to jump to that item in the specification. To filter the list, enter "@" and begin typing the item you want to find.

You can use a colon to jump to a specific line and character number in the specification. To jump to a line, enter a colon followed by the line number, such as ":20". To jump to a character on the line, enter another colon followed by the character number, such as ":20:3". Then select Go to line <number> or Go to line <number> and character <number>.

You can also use the command palette to perform editing commands. In the command palette, enter ">" and select the editing command you want to perform. For example, select Fold All to collapse all sections in the specification, or select Unfold All to expand all sections.

Add new sections using snippets

You can add new sections to your specification using snippets. Snippets are preformatted blocks you can fill out to build your specification. You can use snippets to add the following types of sections:

• OpenAPI - Server, path, operation, response, request body, parameter, callback, schema, security scheme
• AsyncAPI - Server, channel, operation, schema

You can generate a schema from a JSON body if you're more familiar with JSON format. The generated schema is added as a new section to your specification.

To add a new section using a snippet, do the following:

1. Select Specs in the sidebar and select a specification.

2. In the specification outline, select Add next to a supported section type. To add a new schema section using a snippet, you must also select Create new from scratch.

   

3. Select Tab to move between fields in the snippet and add your content.

You can also add a snippet from within the editor. Create a blank line where you want to add a section. Then enter "add" and select the type of section you want to add.

Generate a schema from a JSON body

You can generate a new schema from a request or response body in JSON format, instead of adding a new schema using a snippet.

To generate a new schema using a JSON body, do the following:

1. Select Specs in the sidebar and select a specification.
2. In the specification outline, select Add next to the Schemas section. Then select Generate from JSON body.
3. In the Enter JSON body pane, enter a request or response body in JSON format that represents the schema you'd like to add to your specification. The JSON body will be converted into the specification's language and format in the Generated Schema Preview pane.
4. Select Insert to add the generated schema to your specification.
5. Add a name for your schema.

Edit your specification using autocomplete

Postman offers autocomplete suggestions as you edit your specification. Postman suggests properties and valid values based on the specification type and existing content. Postman also identifies any issues, such as required values that are missing.

View and correct syntax errors

Postman automatically identifies syntax errors as you edit your API specification. Errors can include missing fields, malformed field names, wrong data types, wrong nesting, or other issues. For Postman to be able to check your specification elements, you must use valid JSON or YAML.

To view any syntax errors, select Violations found in definition. Each error shows the error type, the line on which it occurs, and details about the issue. Select an error to highlight it in the specification. You can also get more information by hovering over the error.

Sometimes a single error in your specification can cause more than one issue to appear in the list. As you fix the errors, the issues disappear.