Import Files into an API Project
You can import files, either separately or bundled together in
.zip files, into the projects in which you are creating API specifications and API fragments. The files can be RAML 1.0 files, JSON files, or OpenAPI Specification (OAS) 2.0 files. The files can be on your computer or you can specify a URL for them if they are located online.
- Importing API specifications
You can include more than one API specification in an API-specification project. You might want to have more than one specification in a project if the specifications are closely related in functionality. When you publish your project to Exchange, you select one of the specifications as the main specification.
Additional specifications that you import can be in RAML or OAS. If a specification that you import is written in OAS, the code editor converts the specification to RAML. For information about how OAS 2.0 specifications are converted to RAML 1.0 specifications, see "Import from OAS 2.0 to RAML 1.0" in the documentation for the
oas-raml-convertertool. A link to that documentation is in the See also section at the end of this topic.
- Importing API fragments
Both API specifications and API fragments can include reusable portions that are contained in separate files. For example, suppose you want to use OAuth 2.0 for securing implementations of your API. You might have a security scheme defined in a RAML file named
oauth_2_0.ramlthat explains the settings for implementations to use, as well as other info such as headers and responses. You would import
oauth_2_0.ramlinto your project. Then, in your API specification, you would include the security scheme, as in this example:
securitySchemes: - oauth_2_0: !include oauth_2_0.raml
Then, use the
securedBykeyword to refer to the scheme, as in this example:
securedBy: [ oauth_2_0 ]
You can import annotation types, data types, examples of JSON response payloads, libraries, resource types, security schemes, and traits. If you import an example of a JSON response payload, you can also import the JSON schema, so that developers creating their own response payloads can refer to the schema when doing so.
In the left pane of the editor, click the dots to the right of Files and select Import.
In the Import dialog, select one of these options:
- File or Zip
Select this option if you are importing one or more RAML or JSON files that are located on your computer.
Select this option if you are importing a single RAML or JSON file that is available at a location online.
- OAS file or ZIP
Select this option if you are importing one or more OAS files that are located on your computer.
You cannot import a
.zipfile that contains an OAS specification and JSON files that the specification references. To get around this issue, follow either of these steps:
If the JSON files are in folders, convert the JSON files to RAML before creating the
.zipfile to import.
If the JSON files are not in folders and are at the same level as the specification, import the OAS specification. Then, import each JSON file into your project separately.
- OAS URL
Select this option if you are importing a single OAS file that is available at a location online.
Result: After you click Import, the files are listed in the left pane of the editor. If you imported a
.zipfile that contains the files in a folder structure, the files are listed in that folder structure.