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. 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 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
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.
Before converting a RAML document to OAS 2.0, the converter resolves the following semantics:
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.
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:
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
.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.