OAS/RAML Importing and Exporting Reference

Requires November 2017 Release

After creating a project for an API spec or API Fragment, you can access the Files dropdown to import a single, or multiple zipped RAML, OAS, or OAS specifications. You can also import files having extensions other than .raml, such as user-examples.json, and compressed RAML and JSON files in ZIP format.

Design Center supports files up to 10MB.

You can compress and export all Design Center project files to an external location. You can import the zip file back into Design Center or into Studio.

OAS/RAML Conversion Limitations

  • OAS 2.0 does not support all RAML 1.0 features.

  • Importing a main OAS having references to JSON files included in the zip is not supported.

    The main OAS is converted to RAML. Other referenced folders and JSON files are copied to the project as is (unconverted). See workaround below.

  • You cannot export a RAML fragment into OAS. You can export only a RAML specification defined with #%RAML 1.0.

To import a main OAS having references to JSON files, use one of the following workarounds:

  • Convert dependent JSON files to RAML format prior to compressing the main OAS and dependent files, and then import the zip.

  • First, import an OAS zip having only the main OAS file. Next, import the dependent JSON files into the API design project one at a time.

Importing OAS to RAML

When you import OAS 2.0 to RAML 1.0, the process defines annotations to prevent the loss of any semantics that do not have RAML counterparts.

Exporting RAML to OAS

Before converting a RAML document to OAS 2.0, the converter resolves the following semantics:

  • traits

  • resource types

  • includes

  • libraries

During the RAML to OAS 2.0 conversion, the tool is not expected to preserve all semantical data. For more information, see section, “The lost semantics between translations” in the RAML 1.0 → OAS Complete Functional Specification:

On completion of the conversion, the output is a single OAS document.

Importing an OAS 2.0 Specification

Design Center supports importing an OAS 2.0 specification in JSON or ZIP format from the file system. Exception: Importing an OAS zip having nested references in JSON files is not supported. For more information, see the limitations and workaround above. You can also import an OAS 2.0 specification from the internet. Before attempting to import the document into a Design Center project, first validate the OAS document using the validator at the following URL:

Next, import an OAS 2.0 using the dropdown in the Files panel. In Import, select OAS File or OAS Url from the drop-down. Finally, choose the OAS .zip or .json file to upload or in the text entry box, enter the URL. The converted OAS code appears in RAML in the editor panel.

Users have reported problems due to importing OAS documents that the OAS validator validates. RAML validation requirements are stricter than those of the Swagger parser. Also, when you import OAS 2.0 to RAML 1.0, annotations are defined to prevent the loss of any semantics that do not have RAML counterparts. The annotations might not be supported.