Contact Free trial Login

Create an API Specification with the Code Editor

You can use API Designer’s code editor to create API specifications directly in RAML 0.8, RAML 1.0, or OAS 2.0 (either in JSON or YAML).

Before you begin

Within Anypoint Platform, your user ID must be assigned the Design Center Developer permission.

Procedure

  1. Create an API-specification project that you can work in.

    1. On the Projects page in Design Center, click Create and then click Create API Specification.

    2. In the New Specification section of the dialog that is opened, name your project and select the option Code editor to use the code editor.

    3. Choose whether the stub specification file created in the project should be in RAML or OAS. The default is to create a RAML 1.0 file; however, you can change the file to RAML 0.8 or OAS after the project is created. In fact, projects for creating API specifications can contain a mix of RAML and OAS files.

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

    • The left panel lists the files in your project. The stub specification file is listed. You can change the name and extension of this file by right-clicking the three dots to the right of the name and selecting Rename.

      You can create more than one API specification or related file in a single project. Click the plus sign in the Files panel to create a new file or click the dots that are next to the plus sign to import a file.

    • The central panel displays the editor in which you create the API specification. Appearing in the editor when you create a project or start a new API specification are the first two lines of a specification file in RAML or OAS, depending on which you selected when you created the project. You can change these lines (as well as the file extension) if you want to switch from RAML to OAS or vice-versa.

    • The right panel lists the types and resources that are in the API specification that is in the central panel.

  2. Draft your API specification.

    While you are working in the editor, you can use a large number of commands to navigate through and manipulate the content of your specification. Press F1 at any time to see a list of them. This list also displays keyboard shortcuts for most of the commands.

    You can also perform these tasks:

    Import files and API fragments into your project

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

    For more information about importing files and steps for how to import them, see "Import Files into an API Project", which is linked to from the See also section at the end of this topic.

    For information about adding API fragments to your project, see "Add a RAML API Fragment to an API-Specification Project as a Dependency", which is linked to from the See also section at the end of this topic.

    Simulate calls to your API

    Even while you are drafting an API specification, you can simulate calls to endpoints for which you have specified

    • An HTTP status code the API returns, if successful

    • An example of data the actual implementation would return

      For more information, view the topic "Simulate Calls to an API", which is linked to from the See also section at the end of this topic.

    Export your API project or specification

    At any time, you can export your project as a .zip file. Next to the Files heading in the left pane, click the dots and select Export.

    Download files

    Click the dots to the right of the file name and select Download.

    Download files in a different format

    Click the dots to the right of the file name of a specification and select Download as. You can download your specification in one of the other supported formats. If your specification is in RAML, you can download it in OAS YAML or in OAS JSON. If your specification is in OAS, you can download it in RAML 0.8 or in RAML 1.0.

    The files downloaded through this option are not guaranteed to be valid. This option is intended to provide the basis for the development of a new specification or the continuation of the development of the original specification in a new format.

What to do next

After you are satisfied with your specification, you can publish it to Anypoint Exchange. Click the Publish to Exchange button that is in the top-right corner of the code editor to open the Publish API Specification to Exchange dialog.

Was this article helpful?

💙 Thanks for your feedback!

Edit on GitHub