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.