Swagger UI, Redoc, Scalar and Stoplight Compared

1. What a good API documentation UI needs to deliver

A good documentation UI for a REST API meets four requirements at once. First, it must render the OpenAPI specification completely and correctly, all parameters, schemas, examples, security definitions and response codes. Second, it must be usable by developers seeing the API for the first time, with intuitive navigation, searchable content, and no learning curve required. Third, it should offer try-it-out functionality so consumer developers can exercise endpoints directly in the browser without writing client code. Fourth, it must integrate into existing workflows, including self-hosting, CI pipeline generation, and custom branding.

The four leading tools set different priorities among these requirements. Swagger UI is the oldest and best-known representative, strong on try-it-out, weaker on readability. Redoc prioritizes readability and has no try-it-out. Scalar is the newcomer with the most modern design, combining readability and try-it-out. Stoplight Elements is built as a web component and can be embedded into any design system. The right choice depends on who the documentation primarily serves: internal developers who test a lot, external developers who read a lot, or a corporate documentation platform with its own branding.

2. Swagger UI: the de facto standard with a long history

Swagger UI has been the reference implementation for OpenAPI documentation for more than a decade and comes straight from SmartBear, the maintainer of the OpenAPI specification itself. That makes Swagger UI the reference tool whenever a question arises about what the specification supports. If Swagger UI does not render something, it is usually because the specification does not cover it. For Symfony projects, Swagger UI can be wired in directly through NelmioApiDocBundle, one route, one bundle, and the documentation is live.

The strength of Swagger UI is its try-it-out functionality: developers can enter request parameters, fill in request bodies, set authentication headers and send requests directly in the browser. The response appears right in the UI with status code, response headers and body. This feature is the main reason Swagger UI remains the standard in many teams despite its dated design. The weakness is the UX for documentation readers: the single-column, accordion-based navigation becomes cluttered on large APIs, the typography is functional but not appealing, and the overall design has barely evolved in years.

# config/packages/nelmio_api_doc.yaml
# Swagger UI integration in Symfony via NelmioApiDocBundle

nelmio_api_doc:
    documentation:
        info:
            title: Mironsoft API
            description: REST API for mironsoft.de
            version: 1.0.0
        components:
            securitySchemes:
                bearerAuth:
                    type: http
                    scheme: bearer
                    bearerFormat: JWT
        security:
            - bearerAuth: []
    areas:
        path_patterns:
            - ^/api(?!/doc$)

# routes/nelmio_api_doc.yaml
# Swagger UI available at /api/doc
NelmioApiDocBundle:
    resource: '@NelmioApiDocBundle/config/routing.php'
    prefix: /api/doc

3. Redoc: reader-first, three-column, production ready

Redoc, developed by Redocly, has a clear design philosophy: documentation should be highly readable first and foremost. The result is a three-column layout, navigation on the left, description text and parameter tables in the middle, code examples and schemas on the right. This layout has become the standard for enterprise-grade API documentation and shows up at Stripe, Twilio and GitHub. For external developers who want to understand an API, Redoc is superior to Swagger UI.

Redoc has no built-in try-it-out functionality, and that is a deliberate design decision. The philosophy: a documentation UI should excel at explaining. Testing is a separate task for separate tools. Redocly offers "Try it" as a paid feature on top of Redoc, but the open source project itself does not include it. In Symfony, Redoc can be wired in easily as a self-hosted version. You host the Redoc JS file yourself (or via a CDN) and point it at the generated OpenAPI YAML file. No further backend dependency is needed.

4. Scalar: modern design, developer experience first

Scalar is the youngest of the four candidates and has gained considerable attention in a short time. The project positions itself explicitly as a modern successor to Swagger UI and Redoc, with a noticeably contemporary design, better typography, and a UX that feels like a modern developer platform rather than a tool from 2014. Scalar combines readability and try-it-out in a single UI that presents itself well in both dark and light mode.

The try-it-out feature in Scalar is more thoughtfully built than in Swagger UI: request parameters are cleanly structured, request bodies are easy to edit, and the response display is clearer. Scalar supports multiple languages for client code snippets (curl, Python, JavaScript, PHP, Go) directly in the UI, sparing consumer developers from manually translating the HTTP request into their preferred language. Integration into Symfony works either through a dedicated Symfony bundle or as a minimal routing setup with a simple HTML page that loads the Scalar JS file.

<?php
// src/Controller/ApiDocController.php
// Minimal Scalar integration without external bundle

declare(strict_types=1);

namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

final class ApiDocController extends AbstractController
{
    #[Route('/api/docs', name: 'api_docs', methods: ['GET'])]
    public function __invoke(): Response
    {
        // Self-hosted Scalar, no external CDN dependency
        $html = <<<HTML
        <!DOCTYPE html>
        <html>
        <head>
            <title>Mironsoft API Docs</title>
            <meta charset="utf-8" />
            <meta name="viewport" content="width=device-width, initial-scale=1" />
        </head>
        <body>
            <script id="api-reference"
                data-url="/api/doc.json"
                data-configuration='{
                    "theme": "default",
                    "layout": "modern",
                    "defaultHttpClient": {"targetKey": "php", "clientKey": "guzzle"},
                    "hiddenClients": [],
                    "metaData": {"title": "Mironsoft API Docs"}
                }'
            ></script>
            <script src="/bundles/app/scalar/scalar.min.js"></script>
        </body>
        </html>
        HTML;

        return new Response($html, 200, ['Content-Type' => 'text/html']);
    }
}

5. Stoplight Elements: composable, design-system friendly

Stoplight Elements differs fundamentally from the other three: it is not a finished documentation app but a library of web components. The concept is "bring your own shell", you embed the Elements components into your own design system, your own corporate documentation platform, or your own website. Elements as a web component means it works in any framework: React, Vue, Angular, or plain HTML. That makes it the only one of the four tools that integrates seamlessly into existing design systems.

Stoplight Elements has try-it-out, an optional three-column layout, and fully supports OpenAPI 3.x. Integration into Symfony is similar to Scalar or Redoc: an HTML page with the Elements script and a reference to the OpenAPI YAML file. Stoplight also offers a commercial platform solution for teams that want to run documentation as part of a developer portal. For pure open source use, Elements is free. The weakness: more setup effort than the other three, less of an out-of-the-box solution.

6. Symfony integration: NelmioApiDocBundle and custom setups

NelmioApiDocBundle is the first choice for Symfony projects that want Swagger UI or a configurable documentation UI. The bundle generates the OpenAPI specification automatically from annotations, attributes and PHP types. It supports multiple areas (for example a public API and an admin API with separate documentation pages) and can be configured against any UI tool. From version 4.x onward, NelmioApiDocBundle supports OpenAPI 3.0 and can export the spec as JSON or YAML.

For Redoc, Scalar and Stoplight Elements, no dedicated bundle is needed. You use NelmioApiDocBundle for spec generation and host the UI separately. The pattern: NelmioApiDocBundle generates /api/doc.json, a custom route serves an HTML page that loads Redoc, Scalar or Elements and points it at /api/doc.json. The documentation JS files are either self-hosted (downloaded from npm, placed under public/bundles/) or loaded via a CDN. Self-hosting is preferable for production-safe deployments without external dependencies.

7. Direct feature comparison

# docker-compose.yml: self-hosted Redoc without a Node.js build step
# Serves static Redoc HTML pointing at the Symfony OpenAPI spec

services:
  api-docs:
    image: redocly/redoc:latest
    ports:
      - "8090:80"
    environment:
      SPEC_URL: "https://api.mironsoft.de/api/doc.yaml"
      PAGE_TITLE: "Mironsoft API Docs"
      REDOC_OPTIONS: |
        {
          "hideDownloadButton": false,
          "nativeScrollbars": false,
          "theme": {
            "colors": { "primary": { "main": "#10b981" } },
            "typography": { "fontFamily": "Inter, system-ui, sans-serif" }
          }
        }

8. Summary and recommendation

The choice between Swagger UI, Redoc, Scalar and Stoplight Elements depends on the primary use case. For internal teams that test a lot and are starting out with Symfony, Swagger UI via NelmioApiDocBundle is the simplest solution, minimal setup, usable right away. For public APIs with external developer documentation, Redoc is the proven choice, three-column layout, excellent readability, no distraction from try-it-out. For modern APIs with consumer teams that want both reading and testing, Scalar is the top recommendation, best design, best DX, combining both. For corporate documentation platforms with their own design system, Stoplight Elements is the only sensible option.

No single tool fits every scenario. In practice, a combination often makes sense: NelmioApiDocBundle for spec generation, Scalar or Redoc for public documentation, and Swagger UI as the internal developer view for the team. The spec file itself (/api/doc.json) can be read by all four tools, so switching between them at any point requires no changes to the spec. Investing in a clean OpenAPI specification pays off with every one of the four tools.

9. FAQ: Swagger UI, Redoc, Scalar and Stoplight Compared