Skip to content

Latest commit

 

History

History
65 lines (48 loc) · 4.01 KB

design-import-files.adoc

File metadata and controls

65 lines (48 loc) · 4.01 KB
Raw

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.

About this task

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-converter tool. 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.raml that explains the settings for implementations to use, as well as other info such as headers and responses. You would import oauth_2_0.raml into 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 securedBy keyword 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.

Note

  • If you want your imported files in a folder structure in your project, import a .zip file that contains the files in that folder structure. You cannot create folders in the code editor.

  • If you import a file that is available online by providing its URL, be sure that the file contains no !include statements. The editor imports only the file that is at the URL.

Procedure

  1. In the left pane of the editor, click the dots to the right of Files and select Import.

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

    URL

    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.

    Note

    You cannot import a .zip file 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 .zip file 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 .zip file that contains the files in a folder structure, the files are listed in that folder structure.