Was ist Swagger? OpenAPI-Specification, Tools, Beispiele

Was ist Swagger?

Swagger ist ein Ökosystem von Open-Source-Tools rund um die OpenAPI Specification (OAS) zum Designen, Dokumentieren und Konsumieren von REST-APIs. Ursprünglich von SmartBear entwickelt, wurde die Spec 2016 an die Linux Foundation gespendet und in OpenAPI umbenannt — aber der Name Swagger blieb für das Tooling.

Die OpenAPI Specification (aktuell 3.1) ist ein YAML- oder JSON-Dokument, das eine REST-API beschreibt: Endpoints, Parameters, Request/Response-Schemas, Authentication, Examples. Tools generieren dann Dokumentation, Client-SDKs, Server-Stubs, Mock-Server und Tests aus dieser Spec.

Swagger vs OpenAPI: was ist der Unterschied?

Anatomie einer OpenAPI-Spec

openapi: 3.1.0
info:
  title: Pet Store API
  version: 1.0.0
servers:
  - url: https://api.petstore.example.com/v1
paths:
  /pets:
    get:
      summary: List all pets
      responses:
        '200':
          description: A paged list of pets

Swagger-Ökosystem-Tools

Warum Swagger / OpenAPI nutzen?

• Single Source of Truth.
• Design-first APIs.
• Auto-generierte Client-SDKs.
• Interaktive Docs.
• Mock-Server.
• Contract-Testing.
• Standardisiertes Format.
• Code-first oder Design-first.

OpenAPI 3.0 vs 3.1: was hat sich geändert?

Häufige OpenAPI-Workflows

Design-first (empfohlen)

1. OpenAPI-Spec kollaborativ schreiben.
2. Mit Stakeholdern reviewen.
3. Server-Stubs + Client-SDKs generieren.
4. Business-Logik in Stubs implementieren.
5. Spec für Contract-Tests in CI nutzen.

Code-first

1. Code mit Framework-spezifischen Decorators annotieren.
2. Framework generiert OpenAPI-Spec at Build-Time oder Runtime.
3. Spec serviert at /openapi.json.
4. Swagger UI rendert interaktive Docs.

Fallstricke und Best Practices

• Spec driftet von Realität.
• Fehlende Examples.
• Inkonsistente Naming.
• Zu tiefes Nesting.
• Auth misdocumented.
• Versioning ignoriert.

FAQ: Swagger / OpenAPI

Ist Swagger kostenlos?

Die Open-Source-Tools sind kostenlos. Swagger Hub hat freie und bezahlte Tiers.

Sollte ich Swagger oder Postman nutzen?

Verschiedene Zwecke. Swagger/OpenAPI ist das Spec-Format; Postman ist für Testing/Exploring.

Sollte ich Design-first oder Code-first nutzen?

Design-first für stabile, öffentliche APIs. Code-first für interne/schnell-iterierende APIs.

Was ersetzt Swagger Codegen?

OpenAPI Generator — ein Community-Fork mit aktiverer Entwicklung.

Kann ich Swagger für GraphQL oder gRPC nutzen?

Nein — OpenAPI ist REST-spezifisch.

Wie versioniere ich meine API?

URL-Versioning (/v1/users) oder Header-Versioning.

Load-Testen Sie Ihre Swagger-dokumentierte API mit LoadFocus

Wenn Sie eine OpenAPI-Spec haben und die Implementation load-testen wollen, läuft LoadFocus JMeter- und k6-Scripts gegen Ihre echte API aus 25+ Regionen mit bis zu 12.500 VUs. Registrieren bei loadfocus.com/signup.