How to add Swagger for Gateway?

[P9avel]

Can you provide example using Swagger with proxy?

[samsp-msft]

There is not a swagger endpoint for the proxy - the proxy itself does not directly expose services that would have a swagger definition - it's the destinations of the proxy that might. Depending on the routes the proxy is configured with, it could expose multiple services that each has an OpenAPI definition. In theory you could create a service that would enumerate the routes the proxy supports, takes a OpenAPI definition and does a transform based on the route definition, but that has not been automated.

Depending on how the swagger UI is generated, it may work correctly through the proxy, but it will depend on how it generates links and request URLs for testing services.

[rwkarg]

We do this by probing routes for well known swagger.json endpoints, then expose those via an enumerator like domaindrivendev/Swashbuckle.AspNetCore#1093 (comment)

This allows us to have a single swagger UI served up by the proxy which has a drop down to select one of the routes that exposes a swagger.json file.

Authentication is a bit hit or miss. For example, some backends use PKCE and others don't but the swagger.json doesn't have a way to convey that so it has to be hard coded one way or the other. Haven't found a way to support both yet.

Also need to set up CORS to allow whatever host you're exposing the SwaggerUI as to call in to the actual routes (assuming they're not the same origin).

Other than the mentioned authentication issues, it "works" to select one of the routes on the Swagger UI and Try It! which calls to the backend as expected.

[samsp-msft]

We discussed this in triage. Its not a feature that we are likely to build for YARP, however if the community implements it, we'll seriously consider a PR.

[alexandrehtrb]

+1

[psavoldelli]

This is how I do with Swashbuckle.
This is a work in progress, there is a lot of missing part (matching, cache...)

Create new specs list based on your services:

app.UseSwaggerUI(opt =>
{
    opt.SwaggerEndpoint("/swagger/1.0/swagger.json", "Gateway service by itself- 1.0");
    opt.SwaggerEndpoint("/swagger/serviceA/1.0/swagger.json", "ServiceA - 1.0");
    opt.SwaggerEndpoint("/swagger/serviceB/1.0/swagger.json", "ServiceB - 1.0");
});

Add endpoint to handle specs request

app.UseEndpoints(endpoints =>
{
    // map yarp swagger 
    endpoints.MapGetSwaggerForYarp(_configuration);

    // All controller
    endpoints.MapReverseProxy();
    endpoints.MapControllers().RequireAuthorization();
});

Create swagger options class

internal class GatewaySwaggerSpec
{
    public string Endpoint { get; set; }
    public string Spec { get; set; }
    public string OriginPath { get; set; }
    public string TargetPath { get; set; }
}

Config exemple, the main point is to provide ClusterId inside cluster configuration object to be able to match routes and cluster

{
  "Gateway": {
    "Routes": {
      "serviceA": {
        "ClusterId": "ServiceA",
        "AuthorizationPolicy": "Validated",
        "Match": {
          "Path": "/api/advertising/{**catch-all}"
        },
        "Transforms": [
          { "PathPattern": "/api/{**catch-all}" }
        ]
      }
    },
    "Clusters": {
      "ServiceA": {
        "ClusterId": "ServiceA",
        "Swagger": {
          "Endpoint": "/swagger/serviceA/1.0/swagger.json",
          "Spec": "http://localhost:5003/swagger/serviceA/1.0/swagger.json",
          "OriginPath": "/api/serviceA",
          "TargetPath": "/api"
        },
        "Destinations": {
          "serviceA": {
            "Address": ""
          }
        }
      }
    }
  }
}

Get all swagger to implements from the configuration

  public static void MapGetSwaggerForYarp(this IEndpointRouteBuilder endpoints,IConfiguration configuration)
  {
      var clusters = configuration.GetSection("Gateway:Clusters");
      var routes = configuration.GetSection("Gateway:Routes").Get<List<RouteConfig>>();

      if (clusters != null)
      {
          foreach (var child in clusters.GetChildren())
          {
              if (child.GetSection("Swagger").Exists())
              {
                  var cluster = child.Get<ClusterConfig>();
                  var swagger = child.GetSection("Swagger").Get<GatewaySwaggerSpec>();
                 
                 // Map swagger endpoint if we find a cluster with swagger configuration
                  endpoints.MapSwaggerSpecs(routes, cluster, swagger);
              }
          }
      }
  }

And finaly, this is how I get the swagger spec and filter routes and operations that does not match the proxy configuration

public static void MapSwaggerSpecs(this IEndpointRouteBuilder endpoints, List<RouteConfig> config, ClusterConfig cluster, GatewaySwaggerSpec swagger)
  {
      endpoints.Map(swagger.Endpoint, async context => {
          var client = new HttpClient();
          var stream = await client.GetStreamAsync(swagger.Spec);

          var document = new OpenApiStreamReader().Read(stream, out var diagnostic);
          var rewrite = new OpenApiPaths();

          // map existing path
          var routes = config.Where(p => p.ClusterId == cluster.ClusterId);
          var hasCatchAll = routes != null && routes.Any(p => p.Match.Path.Contains("**catch-all")) ;

          foreach (var path in document.Paths) {

              var rewritedPath = path.Key.Replace(swagger.TargetPath, swagger.OriginPath);

              // there is a catch all, all route are elligible 
              // or there is a route that match without any operation methods filtering
              if (hasCatchAll || routes.Any(p => p.Match.Path.Equals(rewritedPath) && p.Match.Methods == null ))
              {
                  rewrite.Add(rewritedPath, path.Value);
              }
              else
              {
                  // there is a route that match
                  var routeThatMatchPath = routes.Any( p => p.Match.Path.Equals(rewritedPath) );
                  if(routeThatMatchPath)
                  {
                      // filter operation based on yarp config
                      var operationToRemoves = new List<OperationType>();
                      foreach (var operation in path.Value.Operations)
                      {
                          // match route and method
                          var hasRoute = routes.Any(
                              p => p.Match.Path.Equals(rewritedPath) && p.Match.Methods.Contains(operation.Key.ToString().ToUpperInvariant())
                          );

                          if (!hasRoute)
                          {
                              operationToRemoves.Add(operation.Key);
                          }
                      }

                      // remove operation routes
                      foreach (var operationToRemove in operationToRemoves)
                      {
                          path.Value.Operations.Remove(operationToRemove);
                      }

                      // add path if there is any operation
                      if (path.Value.Operations.Any())
                      {
                          rewrite.Add(rewritedPath, path.Value);
                      }
                  }
              }
          }

          document.Paths = rewrite;

          var result = document.Serialize(OpenApiSpecVersion.OpenApi3_0, OpenApiFormat.Json);
          await context.Response.WriteAsync(
              result
          );
      });

[psavoldelli]

Btw do we have a way to retrieve the yarp object configuration directly instead of reading the config files manually?

[Tratcher]

See https://github.com/microsoft/reverse-proxy/blob/main/src/ReverseProxy/Management/IProxyStateLookup.cs

[sorcerb]

Thank you. I will try to write the code above with ProxyState function. I will share when it will be done

[P9avel]

Many thx, sorceb

[alpacat00]

Is it possible to get the list of RouteModel (from IProxyStateLookup.GetRoutes()) or RouteConfig objects with all the transformations already applied? Or do I need to read all of the transforms from the config/proxy state as well and apply them manually?

I'm trying to configure swagger for YARP gateway using code similiar to the above and when I'm filtering the OpenApiPaths I would like to be able to compare them with transformed routes. What would be the best approach to do this?

[Tratcher]

No, transforms aren't applied to routes, they're applied to outgoing requests on a per-request basis.

Why would you include transformed routes in the public swagger?

[alpacat00]

Why would you include transformed routes in the public swagger?

I don't want to include them in swagger, I just need them to compare with paths that are generated in swagger by default.