---
schema_version: "1"
id: 35f215f6110fc7a7f315427263e12d92fbb08e332d6288d69c9384a90bb14e8c
title: Creating and Importing API Specifications
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/anypoint-code-builder/des-create-api-specs.md
canonical_url: https://docs.mulesoft.com/anypoint-code-builder/des-create-api-specs
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 795d95453e61edebca74b2d2e2326af0475874db1de7491fee7aa843e6d8aca8
description: MuleSoft Documentation Site
latest: true
---
---
product: Anypoint Code Builder
version: master
---

# Creating and Importing API Specifications

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use Anypoint Code Builder to create, import, and test API specs before publishing to Anypoint
Exchange. You can start a new spec or import an existing spec from MuleSoft Version Control System
(VCS).

1.  Create an API spec project in Anypoint Code Builder or import the spec from MuleSoft VCS:

    - [Create an API spec project](#design-new-api-spec) (example uses OAS 3.0 (YAML))

    - [Create an API spec project using RAML 1.0](#create-raml-rest-api-spec)

    - [Import an API spec from MuleSoft VCS](#import-spec)

2.  [Track progress in the output panel](#open-output-panel).

3.  [Review your spec in the API console](#review-spec-console).

4.  [Test your spec using the mocking service](#test-spec).

Use the [`oas-example`](#example-oas-api-spec) API spec to explore the functionality of Anypoint
Code Builder with OAS, or see
[Create a REST API Specification Using RAML 1.0](#create-raml-rest-api-spec) for a RAML-first
project.

## Before You Begin

- [Set up and access Anypoint Code Builder](https://docs.mulesoft.com/anypoint-code-builder/start-acb).

- Understand the basics of designing API specs.

  See [Take Your API Specification from Design Through Deployment](https://docs.mulesoft.com/anypoint-code-builder/tutorials#modular-learning-paths)
  for a suggested order of topics.

- Have some familiarity with [business groups](https://docs.mulesoft.com/access-management/business-groups).

  When you publish your API spec to Exchange from Anypoint Code Builder, it requests the name of the
  business group. See [Anypoint Platform Business Groups](https://docs.mulesoft.com/access-management/business-groups).

## Create a New API Specification Project

To create an API spec project in Anypoint Code Builder:

1.  In the activity bar, click the ![](/mulesoft/current/en-us/anypoint-code-builder/_images/icon-ms-logo.png) (**Anypoint Code Builder**) icon.

    ![Anypoint Code Builder icon highlighted in the activity bar](/mulesoft/current/en-us/anypoint-code-builder/_images/anypoint-code-builder-view.png)

2.  From **Create**, click **Design an API**:

    ![\*Design an API\* link highlighted in the \*Create\* section](/mulesoft/current/en-us/anypoint-code-builder/_images/design-api-1.png)

3.  Complete the **API Specification** form:

    <table><colgroup><col> <col></colgroup><thead><tr><th>Field Name</th><th>Field Value</th></tr></thead><tbody><tr><td><div><div><p><strong>Project Name</strong></p></div></div></td><td><div><div><p>Unique name for your project.</p></div><div><p>This name is used as the API spec title in Exchange, the name of the spec file, and the name of the project’s root directory. For example, if the project name is <em>OAS Example</em>, the spec file name is <code>oas-example</code>.</p></div><div><p>To reuse an existing project name, you must delete the project that is already using the name first. See <a href="https://docs.mulesoft.com/anypoint-code-builder/des-delete-api-projects">Deleting API Specs and Fragments</a>.</p></div></div></td></tr><tr><td><div><div><p><strong>Project Location</strong></p></div></div></td><td><div><div><p>Your home directory or another directory you create.</p></div><div><p>See <a href="https://docs.mulesoft.com/anypoint-code-builder/start-add-folders">Adding Folders to Your Home Directory</a>.</p></div><div><p>Don’t create the project within another project directory.</p></div></div></td></tr><tr><td><div><div><p><strong>API Type</strong></p></div></div></td><td><div><div><p>The type of API spec to create.</p></div><div><p>Available options are <strong>REST API</strong> and <strong>AsyncAPI</strong>.</p></div><div><p>Select <strong>REST API</strong> to use the <a href="#example-oas-api-spec">example</a> in this procedure.</p></div></div></td></tr><tr><td><div><div><p><strong>API Specification Language</strong></p></div></div></td><td><div><div><p>See <a href="https://docs.mulesoft.com/anypoint-code-builder/des-designing-api-specs#supported-spec-languages">Supported OAS and RAML Versions</a>.</p></div><div><p>Select <strong>OAS 3.0 (YAML)</strong> to use the <a href="#example-oas-api-spec">example</a> in this procedure.</p></div></div></td></tr></tbody></table>

4.  Click **Create Project**.

    If prompted, trust the authors of the files in the folder.

    When the project is ready for editing, the API project opens the spec in the Editor view, for
    example, this OAS 3.0 (YAML) spec:

    ![New OAS 3.0 (YAML) API project](/mulesoft/current/en-us/anypoint-code-builder/_images/des-oas-create.png)

5.  Continue designing your API spec.

    As you enter elements, use [auto-complete](https://docs.mulesoft.com/anypoint-code-builder/start-discover-ui#auto-complete) (or press
    Ctrl+Space) to display available options within the context.

## Create a REST API Specification Using RAML 1.0

To create a REST API specification project that uses RAML 1.0:

1.  In the activity bar, click the ![](/mulesoft/current/en-us/anypoint-code-builder/_images/icon-ms-logo.png) (**Anypoint Code Builder**) icon.

    ![Anypoint Code Builder icon highlighted in the activity bar](/mulesoft/current/en-us/anypoint-code-builder/_images/anypoint-code-builder-view.png)

2.  From **Create**, click **Design an API**:

    ![\*Design an API\* link highlighted in the \*Create\* section](/mulesoft/current/en-us/anypoint-code-builder/_images/design-api-1.png)

3.  Complete the **API Specification** form:

    <table><colgroup><col> <col></colgroup><thead><tr><th>Field Name</th><th>Field Value</th></tr></thead><tbody><tr><td><div><div><p><strong>Project Name</strong></p></div></div></td><td><div><div><p>Unique name for your project.</p></div><div><p>This name is used as the API spec title in Exchange, as the name of the spec file, and as the name of the project’s root directory.</p></div><div><p>To reuse an existing project name, you must delete the project that is already using the name first. See <a href="https://docs.mulesoft.com/anypoint-code-builder/des-delete-api-projects">Deleting API Specs and Fragments</a>.</p></div></div></td></tr><tr><td><div><div><p><strong>Project Location</strong></p></div></div></td><td><div><div><p>Your home directory or another directory you create.</p></div><div><p>See <a href="https://docs.mulesoft.com/anypoint-code-builder/start-add-folders">Adding Folders to Your Home Directory</a>.</p></div><div><p>Don’t create the project within another project directory.</p></div></div></td></tr><tr><td><div><div><p><strong>API Type</strong></p></div></div></td><td><div><div><p><strong>REST API</strong></p></div></div></td></tr><tr><td><div><div><p><strong>API Specification Language</strong></p></div></div></td><td><div><div><p><strong>RAML 1.0</strong><br>Anypoint Code Builder also supports <strong>RAML 0.8</strong> and OAS formats. For the full list, see <a href="https://docs.mulesoft.com/anypoint-code-builder/des-designing-api-specs#supported-spec-languages">Supported OAS and RAML Versions</a>.</p></div></div></td></tr></tbody></table>

4.  Click **Create Project**.

    If prompted, trust the authors of the files in the folder.

    When the project is ready for editing, the API project opens your root RAML file in the Editor
    view. The file name matches the project name you provided (for example,
    `my-inventory-api.raml`).

5.  Continue designing your RAML spec in the Editor view.

    Use [auto-complete](https://docs.mulesoft.com/anypoint-code-builder/start-discover-ui#auto-complete) (Ctrl+Space or Cmd+Space) to add resources,
    methods, traits, and other RAML constructs in context.

    To add reusable data types and examples from Anypoint Exchange, add fragment dependencies to the
    project and reference them with `!include` directives in RAML. For step-by-step procedures, see
    [Creating and Using API Spec Fragments](https://docs.mulesoft.com/anypoint-code-builder/des-create-api-fragments).

    When you want to try requests against your examples,
    [open the API Console](#review-spec-console) and [use the mocking service](#test-spec) the same
    way you do for OAS projects.

Optional starter RAML for a `/items` resource

```raml
#%RAML 1.0
title: Example Items API

/items:
  get:
    description: List items
```

## Import an API Specification from MuleSoft VCS

Import an API spec from MuleSoft VCS and use Git or another source-control management system
compatible with VS Code to keep your project in sync. For more information, see
[Source Control for API Design Projects](https://docs.mulesoft.com/anypoint-code-builder/des-designing-api-specs#mulesoft-vcs).

> [!NOTE] Importing an API spec from MuleSoft VCS requires Git installed on your computer. If Git is
> not installed on your computer, follow the
> [Git installation instructions](https://github.com/git-guides/install-git) for your machine.

1.  Open the Command Palette.

    Show me how

    - Use the keyboard shortcuts:

      - Mac: Cmd+Shift+p

      - Windows: Ctrl+Shift+p

    - Select **View** > **Command Palette**.

2.  Provide the following command:

    ```command
    MuleSoft: Import API Specification from MuleSoft VCS
    ```

3.  If prompted, log in to Anypoint Platform.

4.  Complete the import process:

    1.  Select your business group from the **Select a Business Group** popup.

    2.  Search for the API spec in the **APIs from MuleSoft VCS** field.

    3.  Navigate to or create a folder for the spec, and click **Select target folder**.

        If you receive an error that the import failed (**Importing project _a\_project\_name_ has
        failed**), check your target folder for a project with the same name. To address a duplicate
        naming issue before importing, you can import the design project to a different target
        folder or delete the project (see
        [Deleting API Specs and Fragments](https://docs.mulesoft.com/anypoint-code-builder/des-delete-api-projects)).

5.  Edit or continue designing your spec, as needed.

    As you enter elements, use [auto-complete](https://docs.mulesoft.com/anypoint-code-builder/start-discover-ui#auto-complete) (or press
    Ctrl+Space) to display available options within the context.

6.  You can sync your changes with MuleSoft VCS.

    This feature is available only for API projects that you import from MuleSoft VCS. You can also
    store your work in another SCM. For SCM options, see [Controlling Source Files](https://docs.mulesoft.com/anypoint-code-builder/start-scm).

## Track Progress in the Output Panel

To track the progress of internal processing as you design your API:

1.  Open the Output panel.

    Show me how

    - Use the keyboard shortcuts:

      - Mac: Cmd+Shift+u

      - Windows: Ctrl+Shift+u

    - Select **View** > **Output**.

2.  Select **Mule DX Server** from the dropdown list:

    ![Mule DX Server in the output pane](/mulesoft/current/en-us/anypoint-code-builder/_images/des-output-panel.png)

To see scaffolding errors only, select **Mule DX Server: Scaffolding** from the list.

## Review Your Spec in the API Console

To display your spec in the console:

1.  Click your spec file in the editor.

2.  Click the ![](/mulesoft/current/en-us/anypoint-code-builder/_images/icon-api-console.png) (**API Console**) icon.

    Alternatively, you can provide the command `MuleSoft: API Console` from the
    [Command Palette](https://docs.mulesoft.com/anypoint-code-builder/start-use-command-palette).

3.  Wait for the endpoints to render in the API Console.

    The API Console shows the endpoints for the spec in API Console, for example:

    ![API spec in the API Console](/mulesoft/current/en-us/anypoint-code-builder/_images/des-api-console.png)

    <table><tbody><tr><td><i data-value="1"></i><b>1</b></td><td>Click a method to view details.</td></tr><tr><td><i data-value="2"></i><b>2</b></td><td>Display the console menu.</td></tr></tbody></table>

4.  Click methods in the console or select items from the menu to view different parts of your spec.
    For example, click **GET**:

    ![API Console with Get details](/mulesoft/current/en-us/anypoint-code-builder/_images/des-api-console-detail.png)

## Test Your API Spec Using the Mocking Service

Use the Mocking Service in the API Console to check the request and responses that you configured in
your API spec.

1.  In Anypoint Code Builder, open the spec for your API project, such as
    [`oas-example`](#example-oas-api-spec).

2.  Click the ![](/mulesoft/current/en-us/anypoint-code-builder/_images/icon-api-console.png) (**API Console**) icon to display your spec in the
    console.

3.  In the API Console, click a method, such as GET or POST.

4.  Click **Try It**:

    ![Try It button in the API console](/mulesoft/current/en-us/anypoint-code-builder/_images/des-api-console-try-it.png)

5.  Confirm that the parameters that you’ve defined are correct and click **Send**.

6.  Verify that API console returns the response you defined, for example:

    ![Example response in the API console](/mulesoft/current/en-us/anypoint-code-builder/_images/des-api-console-response.png)

7.  Optionally, review your configured response examples when querying your mocked API endpoints.

## Example OAS 3.0 (YAML) API Specification

If you created an OAS 3.0 (YAML) project, you can replace the initial spec with following example
code:

Example OAS 3.0 (YAML) API Specification

```YAML
  openapi: "3.0.0"
  info:
    version: 1.0.0
    title: oas-example
  paths:
    /contacts:
      get:
        summary: Retrieve a list of contacts
        description: Returns a list of contacts.
        responses:
          '200':
            description: Successful response
            content:
              application/json:
                example:
                  - id: 1
                    firstName: John
                    lastName: Doe
                    company: Example Corp
                  - id: 2
                    firstName: Jane
                    lastName: Smith
                    company: Another Company

      post:
        summary: Create a new contact
        description: Creates a new contact.
        requestBody:
          description: Contact object to be created
          required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        responses:
          '201':
            description: Contact created successfully
            content:
              application/json:
                example:
                  id: 3
                  firstName: John
                  lastName: Doe
                  company: Example Corp
          '400':
            description: Invalid request
          '500':
            description: Internal server error

    '/contacts/{contactId}':
      put:
        summary: Update a contact
        description: Updates an existing contact based on the contact ID.
        parameters:
          - name: contactId
            in: path
            description: ID of the contact to update
            required: true
            schema:
              type: integer
              format: int64
        requestBody:
          description: Updated contact object
          required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        responses:
          '200':
            description: Contact updated successfully
            content:
              application/json:
                example:
                  id: 3
                  firstName: John
                  lastName: Doe
                  company: Updated Corp
          '400':
            description: Invalid request
          '404':
            description: Contact not found
          '500':
            description: Internal server error

  components:
    schemas:
      Contact:
        type: object
        properties:
          id:
            type: integer
            format: int64
          firstName:
            type: string
          lastName:
            type: string
          company:
            type: string
        required:
          - firstName
          - lastName
```

## See Also

- [Getting Started with Anypoint Code Builder](https://docs.mulesoft.com/anypoint-code-builder/start-acb)

- [Take Your API Specification from Design Through Deployment](https://docs.mulesoft.com/anypoint-code-builder/tutorials#modular-learning-paths)

- [Anypoint Platform Business Groups](https://docs.mulesoft.com/access-management/business-groups)

- [Use Auto-Complete in the Editors](https://docs.mulesoft.com/anypoint-code-builder/start-discover-ui#use-autocomplete)

- [Creating and Using API Spec Fragments](https://docs.mulesoft.com/anypoint-code-builder/des-create-api-fragments)

- [Deleting API Specs and Fragments](https://docs.mulesoft.com/anypoint-code-builder/des-delete-api-projects)

- [Working with Workspaces](https://docs.mulesoft.com/anypoint-code-builder/start-workspaces)