Swagger(OpenAPI specification)

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.

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.

Revolutionize Your Business With Generative AI

From product design and software development to virtual agents, content creation, and reporting, GenAI is transforming business. Our AI experts help you unlock GenAI’s full potential and drive growth.

Let’s Get Started

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