How to use my custom Layout for Swagger UI in DarkaOnLine / L5-Swagger in Laravel 9

ONLINECAST

2 min read

·

05-10-2024

7

0

Share

Dark Mode Delight: Customizing Swagger UI in Laravel 9 with DarkaOnLine / L5-Swagger

Tired of the bright white glare of the default Swagger UI? Want a more visually appealing and user-friendly experience for your API documentation? This article will guide you through the process of integrating a custom layout, specifically designed for dark mode, into your Laravel 9 project using the popular L5-Swagger package.

Scenario:

Imagine you've built a robust API using Laravel 9 and are showcasing it with Swagger UI. However, you're not a fan of the standard bright white theme and would prefer a darker, more modern aesthetic.

Original Code:

The following code snippet illustrates a typical L5-Swagger setup in Laravel 9, where we use the default Swagger UI layout:

// config/l5-swagger.php
return [
    'api' => [
        'base_path' => env('API_BASE_URL', 'api'), // Base URL of your API
        'title' => 'My Laravel API', // Title of your API documentation
        'description' => 'Documentation for my Laravel API',
        'version' => '1.0.0', // API version
    ],
    'routes' => [
        // ... other settings ...
    ],
    'ui' => [
        // ... other settings ...
    ],
];

Dark Mode Magic:

To inject your custom dark theme into Swagger UI, we'll leverage the DarkaOnLine library, which offers pre-built dark mode stylesheets for Swagger UI.

Here's the breakdown:

1. Install DarkaOnLine:

   composer require darkaonline/swagger-ui-theme
   

2. Integrate the Dark Theme: Within your config/l5-swagger.php, locate the ui array and add the following:

   'ui' => [
       'theme' => 'dark',
   ],
   

   This tells L5-Swagger to utilize the dark theme provided by DarkaOnLine.

3. Optional: Customize Further: If you desire additional customization beyond the pre-defined dark theme, you can utilize the customCss setting. This allows you to add your own CSS rules to tailor the Swagger UI look and feel.

   'ui' => [
       'theme' => 'dark',
       'customCss' => [
           'css/my-swagger-styles.css', // Path to your custom CSS file
       ],
   ],
   

Enhance Your API Documentation:

By integrating DarkaOnLine, you'll achieve a visually stunning dark mode theme for your Swagger UI. This not only improves the aesthetics but also enhances readability, especially in low-light environments.

Additional Tips:

• Consider DarkaOnLine's Other Themes: Explore DarkaOnLine's diverse collection of themes.
• Tailor Your Custom CSS: Use the customCss option to refine specific elements of the Swagger UI, including colors, fonts, and layout.
• Accessibility: Ensure your custom theme is accessible to all users by adhering to web accessibility guidelines.

Remember: Always test your customizations thoroughly to ensure they don't break any core functionalities of Swagger UI.

With these steps, you'll transform your API documentation into a visually appealing and user-friendly experience, leaving your developers and API consumers thrilled.