Salesforce / Mulesoft

Swagger(OpenAPI specification)

0101 Small

Introduction

Swagger/OpenAPI specification are the best for design, document and managing Restful API’s.  Since MuleSoft  joined the OpenAPI Initiative of the Linux Foundation,  MuleSoft’s Anypoint Platform explicitly supports Swagger/OAS for describing APIs. MuleSoft Design Center supports importing an OAS 3.0 specification in JSON or ZIP format from the file system. And we can import an OAS 3.0 specification from the internet.

In this article, we will demonstrate how we can use OAS 3.0 API Specification in MuleSoft for API design, implementations and managing.

 

Overview

We can design, implement, deploy, and operate APIs using native OpenAPI Specification (OAS) 3.0 formats in Anypoint Platform. Support for OAS 3.0 is included in API Designer, Anypoint Studio, Anypoint Exchange, API Manager, and Anypoint API Community Manager.

We can catalog existing OAS 3.0 API specifications to share with partners, customers, and developers in the platform or in internal and external API communities. And we can manage and secure your OAS 3.0 APIs by applying appropriate policies.

I will be showing in this article how we can design OpenAPI specification in Anypoint Platform, publishing to exchange and managing API in API Manager.

API lifecycle stages in Anypoint Platform

OAS 3.0 is supported by all the products in Anypoint Platform for the API lifecycle stages of design, publish, and manage.

API Lifecycle Stage Product OAS 3.0 Supported? Additional Information
Design API Designer Yes You can create an OAS 3.0 API specification or import one from Anypoint Exchange.
Design Anypoint Studio Yes You can import an OAS 3.0 API specification from Design Center as an editable API specification project in Studio. You can also create an API specification project from scratch in Studio and then synchronize it with Design Center.
Publish Anypoint Exchange Yes You can download, and publish an OAS 3.0 specification and view the specification documentation in Exchange.
Publish Anypoint API Community Manager Yes You can publish an OAS 3.0 specification and view the specification documentation.
Publish REST Connect Yes You can publish an OAS 3.0 specification but when a connector cannot be generated from the API specification an email is sent to the user, explaining the cause of the error.
Implement Anypoint Studio Yes You can import your OAS 3.0 API specification from Exchange or Maven and write your flows.
Deploy Mule runtime engine Yes OAS 3.0 is supported in Mule runtime engine.
Operate API Manager Yes OAS 3.0 is supported in API Manager.

Designing OAS in Anypoint Platform:

There are many ways we can create/convert OAS in Anypoint platform using design center. Let me explain the how we can create new OAS in design center.

  1. creating a new API-specification project, select OAS 3.0 in the Language field.
  2. Edit the OAS 3.0 contact based on your API requirements. We can create specification in JSON, YAML format. I have created contacts API specification in design center.
  3. Or we can import existing OAS 3.0 specifications from Anypoint Exchange or from your filesystem
  4. Click the gear icon in the top-right corner of the text editor.
  5. Select either of these options:
    1. Select Import from Exchange to see both of these lists:
      1. A list of the API specifications that are available from the business organization that your user ID belongs to in Anypoint Platform.
      2. A list of the API specifications that are published by MuleSoft
    2. Select Import to import an API specification from your local filesystem.
  6. Develop and edit OAS 3.0 specifications.
  7. View documentation
  8. Simulate calls to methods that are in OAS 3.0 API specifications by activating the mocking service.

Publish in Anypoint Exchange:

Whatever we created in design center we can publish to Anypoint Exchange. Click on publish button on right corner of the project in Anypoint Design center.

Salesforce - Make Salesforce Stick
Make Salesforce Stick

To ensure your Salesforce implementation or migration goes as planned, our team of change management professionals discuss how to manage the transition process to ensure your team is ready, willing, and able to perform effectively in the new environment.

Get the Guide

Select the version and click on Publish to Exchange.

Now we can go to exchange and see the API Design document.

Implement in Anypoint Studio:

Now are going to implement the API using the OAS design document in Anypoint Studio.

  1. Create Mule Project in Anypoint Studio. Enter the project name and import a published API by searching the API which we published in exchange in above step.
  2. we click on finish, we should able to see the flows which are generated and we can do our business logic on top of it.

Deploy the application and test:

In the above steps we implemented a Mulesoft API which generated basic flows using OAS design document. Now we can deploy the application in runtime manager and we can test it.

Right click on project in Anypoint Studio and select Run as Mulesoft Application. It will deploy in Mulesoft runtime. As this application have GET, POST methods with contacts resource name we can test using API console using below URL.

http://localhost:8081/console/

You can select GET method and click on Send button. We should able to see 200 status code with response.

You can remove the firstName from request and click on Send in POST method. It will return 400 status code with Bad Request message.

Manage API in Anypoint API Manager:

Below are main types of OAS 3.0 APIs  in API Manager:

  • Basic Endpoint for Mule applications (callbacks not supported)
  • Basic Endpoint for non-Mule applications
  • Endpoint with proxy (callbacks not supported)

We can manage your OAS 3.0 APIs by creating versions and instances and applying policies from API Manager.

  1. In API Manager click on Manage API and select Manage API from Exchange. Search for API Name and select appropriate api.
  2. All the values will be populated automatically. Select Mule version and click on Save.

We can apply the policies on top of it and we can manage this API as per our requirements.

 

Contact us to learn more about what you can do with MuleSoft.

Resources and references:

https://blogs.mulesoft.com/news/anypoint-platform/api-adoption-with-oas-3/

https://blogs.mulesoft.com/news/anypoint-platform/oas-3-0-full-api-lifecycle-support/

https://docs.mulesoft.com/release-notes/platform/oas3

 

About the Author

Meron is a senior technical consultant at Perficient. She has extensive experience in application integration, design, and implementation using Mulesoft. Meron is part of multiple Mulesoft implementations and helps customers to deliver products on time.

More from this Author

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.