Root Files in Projects in the Text Editor in API Designer

In API-specification projects that you create in the text editor and in API-fragment projects, one file is always designated as the "root file." In the Files pane, the root file is indicated with a rectangle that is labeled Root file. When you publish your project to Anypoint Exchange, the root file sets the context for the parser that validates the files in the project.

For example, suppose that a RAML API-specification project contains two specifications, each including (with the !include keyword) a different set of API fragments that are also in the project. When you publish the project to Exchange, all of the files in the project are published. However, Exchange needs to validate the specification and the files that it includes. Without a root file, Exchange cannot ascertain which file to parse first and which set of files to parse.

As another example, suppose that you want to publish an API-fragment project that contains several fragments, one of which is independent and the remaining files of which are a library fragment and its dependencies. If no root file is specified in the project, Exchange cannot parse the files correctly. In this case, you could set the independent fragment as the root file, indicating to Exchange that the file can be parsed alone. Alternatively, you could set the library file as the root file, indicating to Exchange that parsing should begin with that file and proceed to the dependent fragments.

The first time that you open in the text editor a project that was created before the February 8, 2020 release of API Designer, you are prompted to set a root file.

Root Files in API-Specification Projects in the Text Editor

Every API-specification project is created with a default root file. You can switch the root file when there is more than one specification in a project.

The Default Root File

When you create an API-specification project, the file that is created by default is set to be the root file:

The default root file in an API-specification project named "Orders API"

1	The name of the RAML API-specification project is `Orders API`.
2	The default file, which is named `orders-api.raml` and is set as the root file because every API-specification project must have a root file.

Setting the Root File in an API-Specification Project That Contains More Than One Specification

When you import a specification into a project, API Designer asks whether you want to set the specification as the root file of the project.

You can set any specification in an API-specification project as the root file of that project. For example, the following image shows that a project contains two specifications:

An API-specification project with two specifications. The current root file is the RAML version of the specification.

1	The OAS version of the Inventory Process API specification.
2	The RAML version of the same specification. This version of the specification is currently set as the root file.

When you click the three dots to the right of a specification that is not currently the root file, the menu that appears provides an option for setting that specification as the root file:

The Set as root file option at the top of the menu opened by clicking the three dots.

1	The three dots that open the action menu for a file when clicked.
2	The Set as root file option at the top of the action menu.

Root Files in API-Fragment Projects

Every API-fragment project is created with a default root file. You can switch the root file when there is more than one fragment in a project.

The Default Root File in API-Fragment Projects

When you create an API-fragment project, the file that is created by default is set to be the root file:

The default root file in an API-fragment project named "Retail Common."

1	The name of the RAML API-fragment project is Retail Common.
2	The default file, which is named `retail-common.raml` and is set as the root file because every API-fragmentation project must have a root file.

Setting the Root File in an API-Fragment Project That Contains More Than One Fragment

When you import a fragment into an API-fragment project, API Designer asks whether you want to set the fragment as the root file of the project.

You can set any fragment in an API-fragment project as the root file of that project. For example, the following image shows that a project contains two fragments, the first of which is set as the root file:

An API-fragment project with two fragments.

1	The fragment that is set as the root file.
2	The other fragment.

When you click the three dots to the right of a fragment that is not currently the root file, the menu that appears provides an option for setting that fragment as the root file.