API Designer Reference
API Designer for the RESTful API Modeling Language (RAML) is a web-based editor for authoring RAML specifications. API Designer supports RAML and the Open API Specification (OAS) 2.0, also known as Swagger. When you import an OAS specification, API Designer converts OAS code to RAML.
API Designer release notes list the supported versions of the RAML, JS parser, and API Console. After designing the API to the RAML specification using API Designer, you can implement the API using an SDK, such as APIkit 3.8.1 and later, Osprey, or JAXRS-Codegen.
You can access API Designer in the following ways:
From Anypoint Platform
By downloading API Designer from Github and following instructions to run it locally or embed it in an app
API Designer appears and is divided into three panels:
Shows the default file name
api.ramlfor RAML code. An asterisk precedes the file name to indicate unsaved content.
RAML editor panel
Contains generated code: the default RAML version 1.0, the names of the API, and the API version, which you provided to API Manager.
For simulating the API, this panel displays data types, resources, and methods in your API. Until you define the API, the Console displays an empty Resources list. Turn on the Mocking Service on the top, right-hand side and use Try It.
The files panel lists names of any imported files, such as examples, that you can reference as
include files. From the context menu, you can save, rename, and delete a file.
The RAML editor includes the following functions:
Checks and highlights syntax.
Flags incorrect syntax.
Displays a shelf of hints that you can click to insert the next line of code.
In the RAML Editor, you can hover over a red x problem indicator to see a hint about the problem. For example, an indicator says that the api.raml file has not yet been saved:
You use Project > New File to select the RAML spec version and type of content you plan to include in the .raml file.
The API definition, written in RESTful API Modeling Language (RAML), includes the following things:
An optional [baseURI node] at the root of the RAML document
API resources, for example the collection of all customers or a specific customer
HTTP methods, such as GET, POST, PUT, and DELETE, allowed on each resource
The representation of the request and response messages for each method, such as
GET /customer/1 → response: application/json
Select Save from the Project menu to save the file and extinguish the problem indicator.
From the Project menu, you also select functions for creating a new file and folder, saving all files, importing a single, or multiple zipped RAML, OAS, or OAS specifications. You can also use Project > Import to import files having extensions other than .raml, such as user-examples.json.
You can compress and export all API Designer project files to an external location Project > Export files. In the export files dialog, name the zip file. The
Prevent this page from creating additional dialogs overwrites the zip file on subsequent export operations.
Alternatively, you can accept the default unchecked to create additional files on subsequent export operations.
API Designer zips and exports the file or files in the project to the default download location.
You can use a ZIP file that you export from API Designer in the following ways:
Import the zip file back into API Designer.
Import the zip file into Anypoint Studio 6.x.
OAS 2.0 does not support all RAML 1.0 features.
Importing OAS to RAML
When you import OAS 2.0 to RAML 1.0, API Designer 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:
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.
From the View menu, you can toggle the black/white background color of API Designer.
You right-click a file in the files panel and select Save, Rename, or Delete to perform these operations on a single file. The asterisk that indicates an unsaved file in the files panel, disappears. The error indicator in RAML editor about the unsaved file also disappears.
To save all files in the project, click Project > Save All.
A RAML editor shelf appears at the bottom of API Designer when you click Toggle Shelf Visibility icon at the bottom of the RAML editor panel. Then, when you position the cursor on a valid line for making an entry in the Editor, the shelf displays a list of elements. Click an element to enter its code. Categories of elements are Root, Docs, Parameters, Security, Resources, Traits and Types, Schemas, and Others.
When you place the cursor on a new line and in a different column of the editor, the appropriate elements appear on the shelf for you to click. Click the shelf icon to toggle visibility of the shelf.
API Designer makes suggestions as you type element names in the RAML editor panel. Select a suggestion to enter it into the editor.
Depending on the policy you choose to apply to the API, the RAML definition of the API might need to include a security scheme. You can choose Policies on the API version details page and click the RAML snippet link, if there is one, for the listed policy to get any required RAML snippets.
API Designer supports the capability to import an OAS 2.0 specification. Before attempting to import the document into API Designer, first validate the OAS document using the validator at the following URL:
Next, import an OAS 2.0 using Project > Import. Select OAS spec from the drop-down. Finally, in the text entry box, enter either the URL of an OAS spec or the path and file name of an OAS .zip file. The converted OAS code appears in RAML in API Designer.
API Designer 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, API Designer defines annotations to prevent the loss of any semantics that do not have RAML counterparts. The annotations might not be supported.