Examples of Customizing Swagger UI Appearance and Behavior

Introduction

Customizing Swagger UI appearance and behavior can significantly enhance the user experience when interacting with your API documentation. Swagger UI provides a variety of options for tailoring the interface to meet your needs. In this article, we will explore three practical examples that demonstrate how to customize Swagger UI effectively.

Example 1: Changing the Theme Color

Use Case

In situations where branding is essential, such as for corporate APIs, aligning the Swagger UI with your company’s color scheme can improve recognition and user experience.

// In your Swagger UI initialization
const ui = SwaggerUIBundle({
  url: "https://yourapi.com/swagger.json",
  dom_id: '#swagger-ui',
  presets: [
    SwaggerUIStandalonePreset,
    SwaggerUIStandalonePreset
  ],
  layout: "BaseLayout",
  // Custom CSS to change the theme color
  css: "data:text/css;charset=utf-8,.topbar {
    background-color: #0044cc;
  }"
});

This snippet initializes Swagger UI with a custom CSS rule that changes the top bar’s background color to a blue shade matching a corporate theme. You can modify the color code to fit your branding requirements.

Notes

• Ensure your custom CSS does not conflict with existing styles for a seamless experience.

Example 2: Hiding Unnecessary API Endpoints

Use Case

For APIs with numerous endpoints, it may be beneficial to hide less relevant endpoints from the documentation to streamline user navigation and focus on key functionalities.

const ui = SwaggerUIBundle({
  url: "https://yourapi.com/swagger.json",
  dom_id: '#swagger-ui',
  presets: [
    SwaggerUIStandalonePreset,
  ],
  layout: "BaseLayout",
  // Custom filter to hide specific endpoints
  filter: function(endpoint) {
    const hiddenPaths = ['/path/to/hide', '/another/path/to/hide'];
    return !hiddenPaths.includes(endpoint.path);
  }
});

In this example, a filter function is added to the Swagger UI initialization. It checks if the current endpoint path is in the hiddenPaths array and excludes it from the display. This helps in maintaining focus on the most important endpoints.

Notes

• Update the hiddenPaths array as needed to accommodate changes in your API.

Example 3: Adding Custom JavaScript for Enhanced Interactivity

Use Case

To provide users with additional functionality, you might want to add custom JavaScript that enhances the interactive capabilities of the Swagger UI, such as tooltips or custom error messages.

const ui = SwaggerUIBundle({
  url: "https://yourapi.com/swagger.json",
  dom_id: '#swagger-ui',
  presets: [
    SwaggerUIStandalonePreset,
  ],
  layout: "BaseLayout",
  // Custom JavaScript to enhance UI interaction
  onComplete: function() {
    document.querySelectorAll('.opblock-summary').forEach(function(opblock) {
      opblock.addEventListener('mouseover', function() {
        opblock.style.backgroundColor = '#f0f0f0';
      });
      opblock.addEventListener('mouseout', function() {
        opblock.style.backgroundColor = '';
      });
    });
  }
});

In this example, an event listener is added to each operation block to change the background color on mouseover, enhancing visual feedback for users.

Notes

• Customize the JavaScript to suit your specific interactive needs, ensuring that it does not negatively impact performance or usability.

Conclusion

These examples of customizing Swagger UI appearance and behavior illustrate how you can tailor API documentation to better suit your branding and enhance user interaction. By implementing these customizations, you can create a more effective and user-friendly API documentation experience.