Swagger Support for REST APIs

Swagger is a simple yet powerful representation of any RESTful API. With one of the largest ecosystems of API tooling, thousands of developers are supporting Swagger in almost every modern programming language and deployment environment. With a Swagger-enabled API, organizations get interactive documentation, client SDK generation and discoverability. Read on for more on Swagger API documentation and other important information.

It’s natural that the Neuron ESB Client Connector (i.e. SOAP/REST API services hosted by Neuron ESB) should also create Swagger-enabled APIs. Starting with Neuron ESB 3.5 CU4 the Client Connector does exactly that.

Creating Swagger Documentation

The CU4 release includes a new section in the Neuron ESB Explorer Repository called Swagger Documents (see figure 1). This is where Swagger API documentation can be stored and managed. Users can create a new Swagger document in the Repository by either copying or entering the content of an existing Swagger document or by importing an existing Swagger document from any External URI.

Figure 1

Once a Swagger document is stored in the Repository, the document will automatically be hosted by Neuron ESB at https://localhost:51003/docs/<newlycreatedswaggerdoc>.json. All Neuron ESB managed Swagger Repository documents are hosted on Port 51003. However, the port can be changed by editing the value of the “SwaggerSelfHostingUrl” key in the appSettings section of the  discoveryservice.exe.config configuration file located in the “C:\Program Files (x86)\Neudesic\Neuron ESB v3” folder.

To create Swagger documents from scratch, the Swagger Editor (https://editor.swagger.io ), an online tool, can be used as shown in Figure 2 below.

Figure 2

Using Swagger Documents

In order to assign a Swagger document to the Neuron ESB Client Connector, navigate to the Client Connector Tab then select the Metadata Button, which will present you a “Configure Client Connector Metadata” dialog box. Here either an external Swagger document URI can be provided or a static Swagger document located in the “Swagger Documents” section of the Neuron Explorer ESB Repository can be chosen as shown in Figure 3.

Figure 3

Once a Swagger document is selected from the drop-down selection, or an external Document URI is provided, the Client connector will have Swagger documentation associated with its endpoint. Pointing a web browser to the Client Connector URL along with /help will expose the Swagger documentation.

For example, if the Neuron ESB Client Connector URL was “https://localhost:9192/Users”, then the “https://localhost:9192/Users/Help” URL will redirect users to the Swagger documentation (see Figure 4).

Figure 4

Implementing and Testing

Once a Swagger document (like the one created and shown above) is assigned to the Neuron ESB Client Connector, the implementation for the call either has to already exist or be created. The following example demonstrates how we can create a simple implementation that can be tested by users browsing to the Client Connector’s Swagger document.

Using the Neuron ESB Business Process Designer a simple Process can be created that contains the implementation of the “GetUser” API call as shown in Figure 5 below. The Business Process is then attached to the OnPublish event of the Neuron ESB Publisher assigned to the Client Connector.

Figure 5

The actual implementation for “GetUser is simple and encapsulated within the “Get” C# Process Step shown in Figure 5. The “Get” Process Step expands into the Neuron ESB C# Code Editor as shown in Figure 6. The Code Editor contains C# code to mock users in a list, convert the list to a JSON object, setting the Neuron ESB Message body.

Figure 6 

Once implemented, this Neuron ESB Client Connector API can be tested directly from the Swagger document as can be seen below in Figure 7. Clicking the “Try it out!” button will execute the GetUser API call, returning the Response message.