Creating and Importing API Specifications
Use Anypoint Code Builder to create, import, and test API specs before publishing to Anypoint Exchange:
-
Create a API spec project in Anypoint Code Builder from the IDE or by importing the spec from Design Center:
Use the oas-example
API spec to explore the functionality of Anypoint Code Builder.
Before You Begin
-
Understand the basics of designing API specs.
See the Tutorials for details.
-
Have some familiarity with business groups.
When you publish your API spec to Exchange from Anypoint Code Builder, the IDE requests the name of the business group. See Business Groups.
Create a New API Specification Project
To create an API spec project in Anypoint Code Builder:
-
In the activity bar of the IDE, click the (Anypoint Code Builder) icon.
-
From Quick Actions, click Design an API:
-
Complete the API Specification form:
Field Name Field Value Project Name
Unique name for your project.
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 OAS Example, the spec file name is
oas-example
.To reuse an existing project name, you must delete the project that is already using the name first. See Deleting API Specs and Fragments.
Project Location
Your home directory or another directory you create.
Don’t create the project within another project directory.
API Type
The type of API spec to create.
Available options are REST API and AsyncAPI.
Select REST API to use the example in this procedure.
API Specification Language
Select OAS 3.0 (YAML) to use the example in this procedure.
-
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:
-
Continue designing your API spec.
As you enter elements, use auto-complete (or press Ctrl+Space) to display available options within the context.
Import an API Specification from Design Center
Import an API spec from Design Center, and optionally, keep your project in sync with Design Center by using the Anypoint source control management (SCM) system. Alternatively, use Git or another SCM that is compatible with VS Code in the desktop or cloud IDE. For more information, see Source Control for API Design Projects.
-
Open the Command Palette.
Show me how
-
Use the keyboard shortcuts:
-
Mac: Cmd+Shift+p
-
Windows: Ctrl+Shift+p
-
-
In the desktop IDE, select View > Command Palette.
-
In the cloud IDE, click the (menu) icon, and select View > Command Palette.
-
-
Provide the following command:
MuleSoft: Import API Specification from Design Center
-
If prompted, log in to Anypoint Platform through the IDE.
-
Complete the import process:
-
Select your business group from the Select a Business Group popup.
-
Search for the API spec in the APIs from Design Center field.
-
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 from your IDE (see Deleting API Specs and Fragments).
-
-
Edit or continue designing your spec, as needed.
As you enter elements, use auto-complete (or press Ctrl+Space) to display available options within the context.
-
Optionally, sync your changes with Design Center by using the Anypoint SCM.
This feature is available only for API projects that you import from Design Center. You can also store your work in another SCM. For SCM options, see Controlling Source Files.
Track Progress in the Output Panel
To track the progress of internal processing as you design your API:
-
Open the Output panel.
Show me how
-
Use the keyboard shortcuts:
-
Mac: Cmd+Shift+u
-
Windows: Ctrl+Shift+u
-
-
In the desktop IDE, select View > Output.
-
In the cloud IDE, click the (menu) icon, and select View > Output.
-
-
Select Mule DX Server from the dropdown:
Review Your Spec in the API Console
To display your spec in the console:
-
Click your spec file in the editor.
-
Click the (API Console) icon.
Alternatively, you can provide the command
MuleSoft: API Console
from the Command Palette. -
Wait for the endpoints to render in the API Console.
The API Console show the endpoints for the spec in API Console, for example:
1 Click a method to view details. 2 Display the console menu. -
Click methods in the console or select items from the menu to view different parts of your spec. For example, click GET:
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.
-
In Anypoint Code Builder, open the spec for your API project, such as
oas-example
. -
Click the (API Console) icon to display your spec in the console.
-
In the API Console, click a method, such as GET or POST.
-
Click Try It:
-
Confirm that the parameters that you’ve defined are correct and click Send.
-
Verify that API console returns the response you defined, for example:
-
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
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