Swagger UI, Redoc, Scalar und Stoplight im Vergleich

1. Was eine gute API-Dokumentations-UI leisten muss

Eine gute Dokumentations-UI für eine REST API erfüllt vier Anforderungen gleichzeitig: Erstens muss sie die OpenAPI-Spezifikation vollständig und korrekt rendern – alle Parameter, Schemas, Beispiele, Security-Definitionen und Response-Codes. Zweitens muss sie für Entwickler nutzbar sein, die die API zum ersten Mal sehen – intuitive Navigation, suchbar, ohne Einarbeitung verständlich. Drittens sollte sie Try-it-out-Funktionalität bieten, damit Consumer-Entwickler Endpunkte direkt im Browser testen können, ohne Client-Code zu schreiben. Viertens muss sie sich in bestehende Workflows integrieren lassen – Hosting im eigenen System, CI-Pipeline-Generierung, Custom-Branding.

Die vier führenden Tools haben unterschiedliche Prioritäten bei diesen Anforderungen. Swagger UI ist der älteste und bekannteste Vertreter, stark in Try-it-out, schwächer in Lesbarkeit. Redoc priorisiert Lesbarkeit und hat kein Try-it-out. Scalar ist der Newcomer mit modernstem Design und kombiniert Lesbarkeit und Try-it-out. Stoplight Elements ist als Web Component konzipiert und lässt sich in beliebige Design-Systeme einbetten. Die Entscheidung hängt davon ab, wen die Dokumentation primär bedient: interne Entwickler die viel testen, externe Entwickler die viel lesen, oder eine Unternehmens-Dokumentationsplattform mit eigenem Branding.

2. Swagger UI: der De-facto-Standard mit langer Geschichte

Swagger UI ist seit über einem Jahrzehnt die Referenz-Implementierung für OpenAPI-Dokumentation und kommt direkt aus dem Haus von SmartBear, dem Maintainer der OpenAPI-Spezifikation. Das macht Swagger UI zum Referenz-Tool bei Fragen, was die Spezifikation unterstützt. Wenn Swagger UI etwas nicht rendert, ist es meist nicht in der Spezifikation enthalten. Für Symfony-Projekte ist Swagger UI über NelmioApiDocBundle direkt integrierbar – eine Route, ein Bundle, und die Dokumentation läuft.

Die Stärke von Swagger UI ist die Try-it-out-Funktionalität: Entwickler können direkt im Browser Request-Parameter eingeben, Request-Bodies befüllen, Authentifizierungsheader setzen und Requests absenden. Die Response erscheint direkt im UI mit Statuscode, Response-Headern und Body. Diese Funktion ist der Hauptgrund, warum Swagger UI trotz seines veralteten Designs in vielen Teams Standard bleibt. Die Schwäche ist die UX für Dokumentations-Leser: die einspaltige, akkordeon-basierte Navigation wird bei großen APIs unübersichtlich, die Typografie ist funktional aber nicht ansprechend, und das Gesamtdesign hat sich seit Jahren kaum weiterentwickelt.

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

nelmio_api_doc:
    documentation:
        info:
            title: Mironsoft API
            description: REST API für 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, dreispaltig, produktionsreif

Redoc, entwickelt von Redocly, hat eine klare Design-Philosophie: Die Dokumentation soll zuerst gut lesbar sein. Das Ergebnis ist ein dreispaltiges Layout – links die Navigation, in der Mitte die Beschreibungstexte und Parameter-Tabellen, rechts Code-Beispiele und Schemas. Dieses Layout ist bei API-Dokumentationen der Enterprise-Klasse zum Standard geworden und findet sich bei Stripe, Twilio und GitHub. Für externe Entwickler, die eine API verstehen wollen, ist Redoc Swagger UI überlegen.

Redoc hat keine eingebaute Try-it-out-Funktionalität – das ist eine bewusste Design-Entscheidung. Die Philosophie: Eine Dokumentations-UI sollte exzellent im Erklären sein. Testen ist eine separate Aufgabe für separate Tools. Redocly bietet als kostenpflichtigen Service "Try it" in Redoc an, aber das Open-Source-Projekt selbst hat es nicht. In Symfony lässt sich Redoc als Self-Hosted-Version einfach einbinden – man hostet die Redoc-JS-Datei selbst (oder via CDN) und zeigt auf die generierte OpenAPI-YAML-Datei. Keine weitere Backend-Abhängigkeit nötig.

4. Scalar: modernes Design, Developer Experience im Fokus

Scalar ist der jüngste der vier Kandidaten und hat in kurzer Zeit erhebliche Aufmerksamkeit gewonnen. Das Projekt positioniert sich explizit als moderner Nachfolger von Swagger UI und Redoc – mit deutlich zeitgemäßerem Design, besserer Typografie und einer UX, die sich anfühlt wie eine moderne Entwickler-Plattform, nicht wie ein Tool aus 2014. Scalar kombiniert Lesbarkeit und Try-it-out in einem UI, das sich im Dark- und Light-Mode ansprechend präsentiert.

Die Try-it-out-Funktion in Scalar ist durchdachter als in Swagger UI: Die Request-Parameter werden sauber strukturiert, Request-Bodies lassen sich bequem bearbeiten, und die Response-Anzeige ist übersichtlicher. Scalar unterstützt mehrere Sprachen für Client-Code-Snippets (curl, Python, JavaScript, PHP, Go) direkt im UI – das erspart Consumer-Entwicklern, den HTTP-Request manuell in ihrer bevorzugten Sprache zu übersetzen. Die Integration in Symfony geht über einen eigenen Symfony-Bundle oder als minimales Routing-Setup mit einer einfachen HTML-Seite, die die Scalar-JS-Datei lädt.

<?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-freundlich

Stoplight Elements unterscheidet sich fundamental von den drei anderen: Es ist keine fertige Dokumentations-App, sondern eine Bibliothek von Web Components. Das Konzept ist "Bring your own shell" – man integriert die Elements-Komponenten in das eigene Design-System, die eigene Unternehmens-Dokumentationsplattform oder die eigene Website. Elements als Web Component bedeutet, dass es in jedes Framework funktioniert: React, Vue, Angular, oder plain HTML. Das macht es zum einzigen der vier Tools, das nahtlos in bestehende Design-Systeme integrierbar ist.

Stoplight Elements hat Try-it-out, dreispaltiges Layout (optional), und unterstützt OpenAPI 3.x vollständig. Die Integration in Symfony ist ähnlich wie bei Scalar oder Redoc: Eine HTML-Seite mit dem Elements-Script und dem Verweis auf die OpenAPI-YAML-Datei. Stoplight bietet auch eine kommerzielle Platform-Lösung für Teams, die Dokumentation als Teil ihres Developer-Portals betreiben wollen. Für reine Open-Source-Nutzung ist Elements kostenlos. Die Schwäche: mehr Setup-Aufwand als die anderen drei, weniger Out-of-the-Box-Lösung.

6. Symfony-Integration: NelmioApiDocBundle und Custom Setup

NelmioApiDocBundle ist die erste Wahl für Symfony-Projekte, die Swagger UI oder eine konfigurierbare Dokumentations-UI wollen. Das Bundle generiert die OpenAPI-Spezifikation automatisch aus Annotations, Attributen und PHP-Typen. Es unterstützt mehrere Areas (z.B. eine öffentliche API und eine Admin-API mit separaten Dokumentations-Seiten) und lässt sich auf beliebige UI-Tools konfigurieren. Ab Version 4.x unterstützt NelmioApiDocBundle OpenAPI 3.0 und kann die Spec als JSON oder YAML exportieren.

Für Redoc, Scalar und Stoplight Elements ist kein eigenes Bundle nötig. Man nutzt NelmioApiDocBundle für die Spec-Generierung und hostet die UI separat. Das Muster: NelmioApiDocBundle generiert /api/doc.json, eine eigene Route liefert eine HTML-Seite die Redoc/Scalar/Elements lädt und auf /api/doc.json zeigt. Die Dokumentations-JS-Dateien werden entweder selbst gehostet (Download aus npm, in public/bundles/ platzieren) oder über CDN eingebunden. Self-Hosting ist für produktionssichere Deployments ohne externe Abhängigkeiten zu bevorzugen.

7. Direkter Feature-Vergleich

# docker-compose.yml — Self-hosted Redoc without 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. Zusammenfassung und Empfehlung

Die Wahl zwischen Swagger UI, Redoc, Scalar und Stoplight Elements hängt vom Primärnutzungsfall ab. Für interne Teams, die viel testen und mit Symfony starten, ist Swagger UI via NelmioApiDocBundle die einfachste Lösung – minimal Setup, sofort nutzbar. Für öffentliche APIs mit External-Developer-Dokumentation ist Redoc die bewährte Wahl – dreispaltiges Layout, exzellente Lesbarkeit, keine Ablenkung durch Try-it-out. Für moderne APIs mit Consumer-Teams die sowohl lesen als auch testen wollen, ist Scalar die erste Empfehlung – bestes Design, beste DX, kombiniert beides. Für Unternehmens-Dokumentationsplattformen mit eigenem Design-System ist Stoplight Elements die einzig sinnvolle Option.

Kein Tool passt für alle Szenarien. In der Praxis empfiehlt sich oft eine Kombination: NelmioApiDocBundle für die Spec-Generierung, Scalar oder Redoc für die öffentliche Dokumentation, und Swagger UI als interne Entwickler-Ansicht für das Team. Die Spec-Datei selbst (/api/doc.json) kann von allen vier Tools gelesen werden – der Wechsel zwischen ihnen ist jederzeit ohne Anpassung der Spec möglich. Investition in eine saubere OpenAPI-Spezifikation zahlt sich bei jedem der vier Tools aus.

9. FAQ: Swagger UI, Redoc, Scalar und Stoplight im Vergleich