Manage a multi-file API specification

With a multi-file API specification in Spec Hub, your specification can span across multiple files and folders, improving its organization and management.

Supported multi-file specification formats

Postman supports the following multi-file specifications in Spec Hub:

• OpenAPI 2.0, 3.0, and 3.1
• protobuf 2 and protobuf 3

About multi-file specifications

All files in a multi-file specification are considered the full API specification. Each multi-file specification has a root file that’s the top-level file in your specification where the root object is defined. The root file hosts the operations defined by the API and it can reference other files in your specification.

When you create a multi-file specification or import a multi-file specification, Postman determines the root file based on the references across the files. Your specification can only have one root file.

Create a multi-file specification

Add one or more files to an OpenAPI or protobuf specification to turn it into a multi-file specification. Then you can add more files and folders to your specification from the file manager.

To create a multi-file specification, do the following:

1. Expand Specs in the sidebar, then select the specification.

   If you don’t have a specification, click in the sidebar, select Spec, then select the type of specification you want to create. You can also import a specification.

2. Next to your specification, More actions > Add File. This adds a new file to the file manager in the sidebar, located in the sidebar.

Add files and folders

Once you’ve created or imported a multi-file OpenAPI or protobuf specification, you can add more files and folders and even search them by name, all from the file manager. You can also rename and delete your files and folders.

To add more files and folders to your specification, do the following:

1. Expand Specs in the sidebar and select a multi-file specification.

2. In the file manager, hover over All Files and click Add file or folder, then select one of the following:

   • Add File — Adds a new file.
   • Add Folder — Adds a new folder.

3. Next to a folder, you can also click More actions and then select one of the following:

   • Add File — Adds a new file to the folder.
   • Add Folder — Adds a new folder within the folder.

You can also take the following actions from the file manager:

• To rename files and folders, select More actions > Rename. Update the name then press Return or Enter.
• To delete files and folders, select More actions > Delete. Then click Delete to confirm.
• To search files and folders by name, use the search bar in the sidebar.

Change the root file

Your multi-file specification can only have one root file that’s used to reference other files in your specification. You can change the root file in your OpenAPI or protobuf 2 and protobuf 3 multi-file specification at any time.

To change the root file in a multi-file specification, do the following:

1. Expand Specs in the sidebar.
2. Click a multi-file specification in the sidebar.
3. Next to a file in the file manager, select More actions > Mark as Root file.

Make sure to update the new root file with the root OpenAPI object and references to other files in your specification. Otherwise, Postman can’t parse your specification.