Contact Free trial Login

Create an API Specification with the Text Editor

You can use API Designer’s text editor to create API specifications directly in RAML 0.8, RAML 1.0, or OAS 2.0 or 3.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. On the Projects page in Design Center, click Create new.

  2. Select New API Spec.

  3. In the New API Spec dialog, name your project.

    You can change the name (but not the extension) later, if you want to.

  4. Select the I’m comfortable designing it on my own option.

  5. Choose either the RAML or OAS specification.

    API Designer creates the stubs of your API specification using the specification type and version you choose.

    By default API Designer creates a RAML 1.0 file. You can change the file to RAML 0.8 or OAS after the project is created. Projects for creating API specifications can contain a mix of RAML, OAS, and other types of files.

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

  • The left panel lists the files in your project.

    The stub specification file is listed and set as the root file of the project. You can change the name (but not the extension) of this file by right-clicking the three dots to the right of the name and selecting Rename.

    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.

    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.

    If you do create more than one specification file, you must specify one of them as the root file of your project.

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

    1. 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 in .zip files. The files can be RAML 1.0 files, JSON files, or OpenAPI Specification (OAS) 2.0 or 3.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. Click the gear icon in the top-right corner of the text editor and select Download Project.

    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

If you are satisfied with your API specification, you can publish it to Exchange. See Publish an API Specification.

Was this article helpful?

💙 Thanks for your feedback!

Edit on GitHub