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. Multi-file specifications are supported for OpenAPI 3.0 specifications.

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 OpenAPI 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 additional files to an OpenAPI 3.0 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. Click Specs in the sidebar.
2. If you don't have an OpenAPI 3.0 specification, select Create new specification > OpenAPI 3.0. You can also import an OpenAPI 3.0 specification.
3. Next to your specification, select View more actions > Add File. This adds a new file to the file manager in the sidebar, which is located below the outline.

Add files and folders

Once you've created or imported a multi-file OpenAPI 3.0 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. Click Specs in the sidebar.

2. Click a multi-file OpenAPI 3.0 specification in the sidebar.

3. In the file manager, click Add Files and Folders and then select one of the following:

   • New File - Adds a new file at the top level of your specification.
   • New Folder - Adds a new folder at the top level of your specification.

4. Next to a folder, you can also click View 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 search files and folders by name, click and enter a name.
• To rename files and folders, select View more actions > Rename. Update the name then select Return or Enter.
• To delete files and folders, select View more actions > Delete. Then click Delete to confirm.

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 multi-file specification at any time.

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

1. Click Specs in the sidebar.

2. Click a multi-file OpenAPI 3.0 specification in the sidebar.

3. Next to a file in the file manager, select View more actions > Mark as Root file.

   

4. Click Confirm.

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.