Defining an API Specification

You can define the structure of your API using its specification. You can also generate a collection from a spec.

• Editing your schema
• Generating a collection

Editing your schema

The Definition tab in each API version page contains an editor for your API specification (either one you imported or a sample Postman added when you created the API).

The default schema type is OpenAPI 3.0, with YAML as the default format. To use a different schema type or format, choose it from the dropdown list.

The left pane of the schema editor displays an outline of your schema. When you first open the editor, the top level of nodes will be expanded, and the rest of them collapsed. Click nodes to expand or collapse them. Click an element in the outline to jump to it in the editor. You can also click the outline button to hide or show the outline.

In the schema editor, when you hover over a #ref component and press the Command key, a popover displays the first 200 characters of the reference component. When you Command-click the reference component, it will jump to the reference location.

In the upper right of the schema editor are options to beautify the content, wrap text, copy, and search. When you finish editing your schema, click Save.

Postman will indicate validation errors as you work on your schema.

Generating a collection

The Postman API Builder supports API-first development by providing the option to create a Postman collection directly from a schema. Once you have a saved schema, you will see a Generate Collection option in the upper right of the schema editor.

To create a collection based on your schema, click Generate Collection. You can add the collection as documentation, a test, a monitor, or a mock server. The collection will appear in Collections in the left sidebar. It will be linked to the same version of the API as the schema.

You can also configure how the collection will be generated by clicking Show advanced settings.