Search code examples
javamavenswaggerswagger-uiwebjars

Webjars - Add configuration to Swagger-UI webjar

I'm using the Swagger-UI Webjar and I wanted to include our custom URL via the query parameters.

Problem is this isn't enabled by default anymore.

I would need to add an configuration option or configuration file to the Swagger-UI but I can't seem to find any documentation on it if it can be done. As the Webjars documentation is pretty spare on that part nor couldn't get any wiser in the Swagger-UI Webjar README.

Does anybody know if this is possible and if so could also point me in the right direction how to do it?

Solution

  • Faced the same issue and came up with two (similar) workarounds:

    Option 1: Override 'swagger-initializer.js' in META-INF

    Take swagger-initializer.js from the swagger-ui webjars bundle and copy it to the following path (please make sure it matches your version, I am using 4.13.2):

    /src/main/resources/META-INF/resources/webjars/swagger-ui/4.13.2/swagger-initializer.js

    Then adjust swagger-initializer.js according to your needs, e.g. activate queryConfigEnabled:

    ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// adjusted from /webjars/swagger-ui/4.13.2/swagger-initializer.js
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

window.onload = function() {
  //<editor-fold desc="Changeable Configuration Block">

  // the following lines will be replaced by docker/configurator, when it runs in a docker-container
  window.ui = SwaggerUIBundle({
    urls: [{url:"https://darosh.github.io/openapi-directory-lite/specs/github.com/v3.json", name: "github"},{url: "https://petstore.swagger.io/v2/swagger.json", name: "petstore"}],
    dom_id: '#swagger-ui',
    deepLinking: true,
    queryConfigEnabled: true, // <-- I added this line
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    plugins: [
      SwaggerUIBundle.plugins.DownloadUrl
    ],
    layout: "StandaloneLayout"
  });

  //</editor-fold>
};

    Now you should find the Swagger-UI on the URL as before, but with the adjustments made in your swagger-initializer.js. I successfully tested this approach in a Spring Boot Application.

    Option 2: Create custom html with custom swagger-initializer.js

    Take index.html and swagger-initializer.js from the swagger-ui webjars bundle and copy it to the path that you are serving from. In a Spring Boot Application that could be for example:

    src/main/resources/static/swagger-initializer.js
    src/main/resources/static/swagger-ui.html (I renamed it from index.html to swagger-ui.html for clarity)

    Now adjust the html file to point to the proper webjars location of the swagger-ui resources and point to your own swagger-initializer.js:

    <!--------------------------------------------------------------------------------------------------------------------->
<!-- adjusted from webjars/swagger-ui/4.13.2/schema-template.json-->
<!--------------------------------------------------------------------------------------------------------------------->

<!-- HTML for static distribution bundle build -->
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Swagger UI by Fable</title>
  <link rel="stylesheet" type="text/css" href="/webjars/swagger-ui/swagger-ui.css" />
  <link rel="stylesheet" type="text/css" href="/webjars/swagger-ui/index.css" />
  <link rel="icon" type="image/png" href="/webjars/swagger-ui/favicon-32x32.png" sizes="32x32" />
  <link rel="icon" type="image/png" href="/webjars/swagger-ui/favicon-16x16.png" sizes="16x16" />
</head>

<body>
<div id="swagger-ui"></div>
<script src="/webjars/swagger-ui/swagger-ui-bundle.js" charset="UTF-8"> </script>
<script src="/webjars/swagger-ui/swagger-ui-standalone-preset.js" charset="UTF-8"> </script>
<script src="/swagger-initializer.js" charset="UTF-8"> </script>
</body>
</html>

    Now you can adjust you own swagger-initializer.js to your needs (see Option 1 for example). You can find the adjusted Swagger-UI on a new URL, depending on how you serve your resources. Please make sure that you access your adjusted html file and not the default html file from swagger-ui as this one stays unchanged. I successfully tested this approach in a Spring Boot Application.

    Final Notes

    While Option 1 requires to adjust only one file, Option 2 appears more clean and more flexible to me. Please note that in Option 1 you have to adjust the path to your custom swagger-initializer.js whenever you update your webjar's version as the version is encoded in the path.