Contact Us 1-800-596-4880

Create and Publish an API Fragment in the Text Editor in API Designer

You can create API fragments directly in RAML, OAS 3.0, and JSON Schema with the help of code suggestions that appear within the text editor.

About This Task

An API fragment is a document that has a version and an identifier, but is not in itself a complete specification.
When creating a RAML API fragment you can choose one of the following types defined by RAML.org. See the RAML 0.8 or 1.0 specification (depending on which you want to use) for descriptions of the types:

  • Trait

  • Resource Type

  • Library

  • Type

  • User Documentation

  • Example

  • Annotation Type

  • Security Scheme

To support OAS 3.0 fragment externalization, API Fragments support OAS 3.0 components and JSON Schema:

  • Component (YAML)

  • Component (JSON)

  • JSON Schema

OAS 3.0 components should contain only the reusable component objects for the different aspects of the OAS.

Procedure

  1. On the Projects page in Design Center, click Create +.

  2. Select New Fragment.

  3. In the New Fragment dialog, type a name for the Fragment project.

  4. Select the API specification format.

    You can choose between RAML 1.0, OAS 3.0 and JSON Schema format.

    If you choose RAML 1.0, you can select it’s fragment type.
    You can change the name or fragment type later, if necessary.

  5. Select the type of API fragment that you want to create and click Create Fragment.

    Result: The text editor opens. The editor is divided into three panels:

    • The left panel lists the files in your project.

      You can create new files by clicking +, and then New file. Select the API format of the file between RAML 1.0, OAS 3.0, JSON schema, or other. Select the file type if needed, name your file, and click Create.

      By default, the editor creates a file that has the same name as the project. This file is set as the root file of the project.

      You can set YAML, RAML, or JSON schema files as your root file.

      The left panel also lists the file exchange.json, which is a file that contains metadata required by Anypoint Exchange at the time that you publish your project to Exchange. This file is read-only.

    • The middle panel displays the editor in which you create your API fragment.

    • The right panel lists the types and resources that are in the API fragment displayed in the middle panel.

  6. Draft your API fragment.

    The text editor suggests RAML nodes, methods, and other elements that you can add at the location of your cursor.

    You can import files into your project, either separately or bundled in .zip files. The files can be RAML 1.0 files, JSON files, OpenAPI Specification (OAS) 2.0, or OAS 3.0 files. The files can be on your computer or you can specify a URL for them if they are located online.

What to Do Next

You can publish the API fragment to Anypoint Exchange.

  1. Click the Publish button that is in the top-right corner of the text editor, and then click Publish to Exchange.

  2. Specify a version number for the project, which Exchange treats as an asset. This number is displayed in Exchange in the Version section of the right pane in the page for the project.

In Anypoint Exchange, you can see the asset version of your API-fragment project by clicking View versions.

After you publish the API-fragment project, other developers can include its fragments as dependencies in their own API-specification projects.

When you publish the API-fragment project, Exchange automatically creates an API portal for it.

OAS Components Limitations

The following list displays OAS 3.0 limitations you must consider when writing your API Fragments:

  • Valid fields at the document root level are: openapi, info, components, and paths.

  • Valid fields in the info object are title and version.

  • The paths key must be an empty object.