Skip to content

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.

Swagger-Support-Picture1
Figure 1

Once a Swagger document is stored in the Repository, the document will automatically be hosted by Neuron ESB at http://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 (http://editor.swagger.io ), an online tool, can be used as shown in Figure 2 below.

Swagger-Support-Picture2png
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.

Swagger-Support-Picture3
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 “http://localhost:9192/Users”, then the “http://localhost:9192/Users/Help” URL will redirect users to the Swagger documentation (see Figure 4).

Swagger-Support-Picture4
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.

Swagger-Support-Picture5
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.

Swagger-Support-Picture6
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.

Swagger-Support-Picture7

About the Author

Author's Name
Marty Wasznicky

Vice President, Neuron ESB

Marty has almost 30 years of experience in the software development industry. He joined Neudesic after six years as a Regional Program Manager in the Connected Systems Division at Microsoft. His responsibilities there included building out Microsoft’s BizTalk Server product integration business, managing a team of SOA/ESB/BPM field specialists and building strategic partner alliances. Marty created the Microsoft Virtual Technical Specialist program and owned the development of Microsoft’s Enterprise Service Bus Toolkit.