Swagger-UI and OpenApiFeature plugin

mikesheen · October 5, 2023, 5:10am

I find the version of Swagger-UI that ships with ServiceStack (6.11 or earlier) to be hopelessly slow with larger API’s. I’ve experimented with the latest Swagger-UI and it’s at least 100 times faster on the intial load compared to the current version ServiceStack uses.

So, I’ve embarked on an effort to see what I need to do to use the latest Swagger-UI.

I’ve been reading the docs on replacing the built-in ServiceStack embedded resources relating to Swagger-UI on Open API

If I put the latest Swagger-UI files in a swagger-ui folder, when clicking the Swagger-UI link on the metadata page the OpenAPIFeature adds does use the new Swagger-UI - but it’s not setting the URL for the openapi document to be the /openapi of the API.

I’ve tried a few things like editing the swagger-initializer.js as per the swagger-ui docs, but nothing seems to work - it still is the http://petstore.swagger.io/v2/swagger.json default.

The OpenApiFeature plugin must be weaving some magic to set that URL, but I can’t see where when looking in ServiceStack/src/ServiceStack.Api.OpenApi/OpenApiFeature.cs.

Is there a simple way to use the latest Swagger-UI?

mythz · October 5, 2023, 6:38am

Not sure about magic, but it just replaces the hard coded URL in the static index.html with /openapi at:

github.com

ServiceStack/ServiceStack/blob/main/ServiceStack/src/ServiceStack.Api.OpenApi/OpenApiFeature.cs#L160


      
          if (indexFile != null)
          {
              var html = indexFile.ReadAllText();
              var injectJs = patchFile?.ReadAllText();
              var injectPreloadJs = patchPreLoadFile?.ReadAllText();
          
              return new CustomResponseHandler((req, res) =>
              {
                  res.ContentType = MimeTypes.HtmlUtf8; //use alt HTML ContentType so it's not overridden when Feature.Html is removed
                  var resourcesUrl = req.ResolveAbsoluteUrl("~/openapi");
                  html = html.Replace("http://petstore.swagger.io/v2/swagger.json", resourcesUrl)
                      .Replace("ApiDocs", HostContext.ServiceName)
                      .Replace("<span class=\"logo__title\">swagger</span>", $"<span class=\"logo__title\">{HostContext.ServiceName}</span>")
                      .Replace("http://swagger.io", LogoHref ?? "./");
          
                  if (LogoUrl != null)
                      html = html.Replace("images/logo_small.png", LogoUrl);
          
                  if (injectPreloadJs != null)
                  {
                      html = html.Replace("window.swaggerUi.load();", injectPreloadJs + "\n\n      window.swaggerUi.load();");

But since it’s a completely different UI I wouldn’t consider trying to replace it over the existing OpenApiFeature.

Instead I’d take a copy of the ServiceStack.Api.OpenApi, rename it to something like OpenApi3 that completely replaces the old UI with the new UI.

mikesheen · October 5, 2023, 8:01am

I have no idea why I didn’t properly parse that! I saw the petstore URL and did not cognitively process the fact it was performing a .Replace() of the html document.

Thanks