MMLib.SwaggerForOcelot

If you use an Ocelot Service Discovery Provider, you can use the service name in your Swagger configuration instead of hardcoded hosts and ports. In the SwaggerEndPoints section, use the Service object containing the Name (matching the Ocelot ServiceName) and the Path to the swagger JSON.

"Routes": [
  {
    "DownstreamPathTemplate": "/api/{everything}",
    "ServiceName": "projects",
    "UpstreamPathTemplate": "/api/project/{everything}",
    "UpstreamHttpMethod": [ "Get" ],
    "SwaggerKey": "projects"
  }
],
"SwaggerEndPoints": [
    {
      "Key": "projects",
      "Config": [
        {
          "Name": "Projects API",
          "Version": "v1",
          "Service": {
            "Name": "projects",
            "Path": "/swagger/v1/swagger.json"
          }
        }
      ]
    }
]

SwaggerForOcelot allows you to view and use Swagger documentation for downstream services directly through your Ocelot API Gateway. It aggregates downstream OpenAPI docs and modifies addresses to match the UpstreamPathTemplate defined in your Ocelot configuration.

Prerequisites

1. Ensure your downstream services have Swashbuckle.AspNetCore configured to generate Swagger JSON.
2. Install the NuGet package in your ASP.NET Core Ocelot project: dotnet add package MMLib.SwaggerForOcelot

If you use Ocelot's Request Aggregation feature, you can generate documentation for these aggregate endpoints by enabling the GenerateDocsForAggregates option in your AddSwaggerForOcelot configuration. The documentation will appear on a custom Aggregates page in the Swagger UI.

services.AddSwaggerForOcelot(Configuration,
  (o) =>
  {
      o.GenerateDocsForAggregates = true;
  });

In your ASP.NET Core application, you need to register the generator in ConfigureServices and use the middleware in Configure.

Registration

Use services.AddSwaggerForOcelot(Configuration) in Startup.cs.

Middleware

Use app.UseSwaggerForOcelotUI(...) to expose the interactive documentation. You can customize the PathToSwaggerGenerator (defaults to /swagger/docs).

// In ConfigureServices
services.AddSwaggerForOcelot(Configuration);

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

You can automatically generate Swagger security definitions based on your Ocelot route configuration:

1. Add AuthenticationOptions to your route in ocelot.json using an AuthenticationProviderKey.
2. In Startup.cs, map that AuthenticationProviderKey to a specific security definition name using AddAuthenticationProviderKeyMapping.

// ocelot.json
"Routes": [
  {
    "DownstreamPathTemplate": "/api/{everything}",
    "ServiceName": "projects",
    "UpstreamPathTemplate": "/api/project/{everything}",
    "SwaggerKey": "projects",
    "AuthenticationOptions": {
      "AuthenticationProviderKey": "Bearer",
      "AllowedScopes": [ "scope" ]
    }
  }
]

// Startup.cs
services.AddSwaggerForOcelot(Configuration,
  (o) =>
  {
    o.AddAuthenticationProviderKeyMapping("Bearer", "appAuth");
  });

When aggregating services where parameter names differ (e.g., {id} in one service and {buyerId} in another), use the ParametersMap property in your Ocelot configuration. The key is the parameter name used in the Ocelot configuration, and the value is the parameter name used in the downstream service.

{
  "DownstreamPathTemplate": "/api/basket/{id}",
  "UpstreamPathTemplate": "/gateway/api/basket/{id}",
  "ParametersMap": {
    "id": "buyerId"
  },
  "ServiceName": "basket",
  "SwaggerKey": "basket",
  "Key": "basket"
}

To improve performance when downstream documentation is large, enable caching by setting the DownstreamDocsCacheExpire property in the AddSwaggerForOcelot setup. The cache will automatically refresh if the downstream documentation changes.

services.AddSwaggerForOcelot(Configuration,
            setup =>
            {
                setup.DownstreamDocsCacheExpire = TimeSpan.FromMinutes(10);
            });

If your downstream services define multiple servers or use server templating that you want to preserve on the gateway, set TakeServersFromDownstreamService to true in the SwaggerEndPoints configuration.

Note: When this is enabled, the server path is not used to transform the paths of individual endpoints.

"SwaggerEndPoints": [
    {
      "Key": "users",
      "TakeServersFromDownstreamService": true,
      "Config": [
        {
          "Name": "Users API",
          "Version": "v1",
          "Service": {
            "Name": "users",
            "Path": "/swagger/v1/swagger.json"
          }
        }
      ]
    }
]

By default, descriptions are pulled from downstream documentation. To provide a custom description for an aggregate route, add a Description field to the aggregate object in your ocelot.json configuration.

"Aggregates": [ 
  {
    "RouteKeys": [
      "user",
      "basket"
    ],
    "Description": "Custom description for this aggregate route.",
    "Aggregator": "BasketAggregator",
    "UpstreamPathTemplate": "/gateway/api/basketwithuser/{id}"
  }
]

If a downstream service is hosted within a virtual directory (e.g., /project/api/...), you must set the VirtualDirectory property in the Ocelot route configuration to ensure paths are correctly replaced.

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