Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

How to insert minor customization into Swagger UI inside its markup?

I have a .NET Core project documented using Swashbuckle (Swashbuckle.AspNetCore.SwaggerGen 3.0.0 and Swashbuckle.AspNetCore.SwaggerUi 3.0.0). My aim's to add a custom tag right below the DIV with class title (i.e. below the service's name but above the endpoints).

When I investigate Swagger UI markup, I see there's a DIV with class swagger-ui and I'd like insert my stuff into it, so to speak. The setup I have today is a file called donkey.html which is being rendered when I access the URL of Swagger UI looking as follows.

...
<body>
  <div id="swagger-ui"></div>
  <div id="api_info"></div>
  <!-- ... -->
  <script src="./swagger-ui-bundle.js"></script>
  <script src="./swagger-ui-standalone-preset.js"></script>
  <script type="text/javascript">
    (function () { ... })();
  </script>
</body>
</html>

I've googled for a few hours now and read a lot about OpenAPI and YAML among other things. However, the impression I'm getting is that it requires a whole rebuild of the Swagger UI project and my ambition targets a much simpler task at the moment.

Is there a way to jack the DIV called api_info so it renders as a part of swagger_ui with out regenerating the whole Swagger UI project?

I tried to augment onto the base layout as shown here but that ended poorly and turned out to be a bit more complicated than what I'm aiming for. Perhaps it's the only feasible approach to create a module, in which case I'll consider it, but that's the last resource in this case.

like image 394
Konrad Viltersten Avatar asked Dec 06 '22 11:12

Konrad Viltersten


1 Answers

Swagger UI 3.x has the plugin system that lets you add or modify UI elements. Some documentation on plugins can be found at:
Plugins
What's the intended way of customizing SwaggerUI 3.x?

There is no need to recompile Swagger UI to use plugins, you can actually define the plugins directly in the index.html page. To add or change UI elements, you need a plugin that uses wrapComponents and React.createElement to build the desired DOM structure. (See also React Without JSX.)

For the custom plugins to have effect, they must be added to the plugins list in the SwaggerUIBundle constructor.

Example

Here is a sample plugin that adds custom <h3> headers above and below the API title:

// index.html

<script>
window.onload = function() {

  // Custom plugin that adds extra stuff
  const MyCustomPlugin = function() {
    return {
      wrapComponents: {
        // add text above InfoContainer - same effect as above title
        InfoContainer: (Original, { React }) => (props) => {
          return React.createElement("div", null,
            React.createElement("h3", null, "I'm above the InfoContainer"),
            React.createElement(Original, props)
          )
        },

        // and/or add text above API description
        InfoUrl: (Original, { React }) => (props) => {
          return React.createElement("div", null,
            React.createElement(Original, props),
            React.createElement("h3", null, "I'm above the API description")
          )
        }
      }
    }
  }


  const ui = SwaggerUIBundle({
    url: "http://petstore.swagger.io/v2/swagger.json",
    dom_id: '#swagger-ui',
    ...
    plugins: [
      MyCustomPlugin,       // <------ add your custom plugin here
      SwaggerUIBundle.plugins.DownloadUrl
    ],
    ...

The result looks like this:

Swagger UI with customized layour

like image 89
Helen Avatar answered Dec 28 '22 05:12

Helen