Nav

OAS/RAML Importing and Exporting Reference

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.

Design Center supports files up to 10MB.

You can compress and export all Design Center project files to an external location. Selct Files > Export. In the export files dialog, name the zip file. You can use a ZIP file that you export from Design Center in the following ways:

  • Import the zip file back into Design Center.

  • Import the zip file into Studio.

OAS/RAML Conversion Limitations

  • OAS 2.0 does not support all RAML 1.0 features.

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

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:

https://github.com/mulesoft/oas-raml-converter

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. 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:

http://bigstickcarpet.com/swagger-parser

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.