Edit your API specification

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 identifies syntax errors and API governance issues, and shows details so you can fix 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 click 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, click 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, click View Command Palette in the upper right. You can also click ⌘+Shift+O or Ctrl+Shift+O.

In the command palette, click 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 click 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 click the editing command you want to perform. For example, click Fold All to collapse all sections in the specification, or click Unfold All to expand all sections.

Add new sections using snippets

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

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

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

1. In the specification outline, click next to a supported section type to add it to your specification using a snippet. Clicking displays a dropdown list if the section supports more than one section type.

   

   If the Servers or Tags sections are missing from your OpenAPI 3.0 specification, you can expand these sections in the specification outline and click Add. This adds the respective section to your specification using snippets.

2. Make a selection from the dropdown list if the section supports more than one section type:

   • When you click next to the Schemas section, you can add a schema using a snippet or generate a schema from a JSON body.
   • (OpenAPI 3.0 only) When you click next to the Components section, you can select a supported section type to add it using a snippet.

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 click the type of section you want to add.

Note the following when using snippets with OpenAPI 3.0 specifications:

• You can't add sections using snippets if Postman identifies syntax errors in your specification. Learn how to view and fix syntax errors in your specification.
• You can't use snippets to add more sections than are needed to complete the specification. For example, if an operation already has a request body, Postman prevents you from adding another request body using snippets.

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. In the specification outline, click next to the Schemas section. Then click Generate from JSON body.
2. 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.
3. Click Insert to add the generated schema to your specification.
4. 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 syntax errors and API governance issues, and shows details so you can fix them.