Using Swagger with Ocelot API Gateway

I was recently trying to configure Swagger on the Ocelot API gateway for one of the projects at work and realized that there aren't many blogs or details available and hence the idea to write this post. Let's get this party started! :)

Out of the box, the Ocelot API gateway doesn't support Swagger integration. You can read about it here. After some amount of search, I found an npm package — MMLib.SwaggerForOcelot that allows us to let Swagger be configured on top of the Ocelot API gateway (You can go through their GitHub page as well)

Architecture

I am using a sample image for the architecture from one of the Microsoft documentation that I referred for our project.

I am using VS 2019 and dot net core microservices projects.

eShopOnContainers architecture with API Gateways — Source

Configuration

Most of Ocleot and Swagger are just configurations in JSON files and hardly a few lines of code in the project. So Let's get configuring:

Step 1: Setup and Configure Ocelot in your project

Please follow this.

Step 2: Setup Swagger for all the microservices

Please follow this.

Step 3: Setup Swagger for your API gateway

Please follow the same as Step 2.

Step 4: Setup Swagger in your API gateway project using MMLib.SwaggerForOcelot package

a. Install Nuget package into yout ASP.NET Core Ocelot project.

dotnet add package MMLib.SwaggerForOcelot

b. Configure SwaggerForOcleot in ocelot.json

In the ocelot.json routes that you configured in Step 1 ( as shown below ), add “SwaggerKey: <servicename>”.

"Routes": [
    {
      "DownstreamPathTemplate": "/api/{everything}",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [
        {
          "Host": "localhost",
          "Port": 5100
        }
      ],
      "UpstreamPathTemplate": "/api/contacts/{everything}",
      "UpstreamHttpMethod": [ "Get" ],
      "SwaggerKey": "contacts"
    }
]

c. Add the “SwaggerEndPoints” section in the ocelot.json

The “Key” should match the “SwaggerKey” in the Routes section and the “Url” should match the location where your service is hosted and the location where this configuration can find the service’s swagger.json file. This location is the same as provided in the StartUp.cs of each of the services you are working on and where Swagger is configured using Step 2.

"SwaggerEndPoints": [
    {
      "Key": "contacts",
      "Config": [
        {
          "Name": "Contacts API",
          "Version": "v1",
          "Url": "http://localhost:5100/swagger/v1/swagger.json"
        }
      ]
    }
]

You need to add EndPoints of all the services in your system.

d. In the ConfigureServices method of Startup.cs, register the SwaggerForOcelot generator.

services.AddSwaggerForOcelot(Configuration);

e. In the Configure method, insert the SwaggerForOcelot middleware to expose interactive documentation.

app.UseSwaggerForOcelotUI(opt => {
  opt.PathToSwaggerGenerator = "/swagger/docs";
})

You can now build and run your API gateway project along with all the services you have configured and on the browser go to http://ocelotprojecturl:port/swagger to view the Swagger documentation.

Source

This is the simplest implementation of Swagger with Ocelot. There are a lot of configurations available for this and the creators of the MMLib.SwaggerForOcelot are always updating with new features and bug fixes.

I am still in the process of exploring more configurations and will provide an update soon.

I hope this helps. Cheers!