Was ist Swagger? Swagger und OpenAPI erklärt

Was ist Swagger?

Swagger ist die Familie von Open-Source-Werkzeugen, allen voran Swagger UI und Swagger Editor, rund um die OpenAPI Specification, das Standardformat zur Beschreibung von HTTP-APIs. Sie schreiben eine maschinenlesbare Beschreibung Ihrer API, und Werkzeuge machen daraus interaktive Dokumentation, Client- und Servercode, Mock-Server und Tests. "Swagger" war außerdem der ursprüngliche Name der Spezifikation selbst.

Swagger und OpenAPI

Die beiden Namen sorgen für die meiste Verwirrung, daher hier die Trennung:

• OpenAPI Specification (OAS) ist das Format: ein JSON- oder YAML-Dokument, das Endpunkte, Parameter, Request- und Response-Schemas sowie Authentifizierung beschreibt. Die aktuell veröffentlichte Version ist zum Zeitpunkt dieses Textes 3.2.1.
• Swagger ist der alte Name der Spezifikation (bis zur Umbenennung am 1. Januar 2016) und heute der Name der Werkzeuge von SmartBear dazu. Eine "Swagger-2.0-Datei" nutzt noch die alte Benennung und wird von Swagger UI weiterhin gelesen.
• Swagger UI stellt eine OpenAPI-Beschreibung als durchsuchbare Dokumentation dar und lässt Leser jede Operation ausprobieren. Es liest Swagger-2.0- und OAS-3.x-Dateien.
• Swagger Editor ist ein Editor zum Schreiben von OpenAPI-Beschreibungen mit Live-Vorschau und Validierung.

Kurz zur Geschichte: Swagger entstand 2011 und wurde im September desselben Jahres als Open Source veröffentlicht. Im November 2015 half SmartBear dabei, die OpenAPI Initiative unter dem Dach der Linux Foundation zu gründen, und die Spezifikation wurde zu OpenAPI.

So sieht eine OpenAPI-Beschreibung aus

Verpflichtend sind nur openapi und info (mit title und version) sowie mindestens eines von paths, components oder webhooks. Ein kleines funktionierendes Beispiel:

openapi: 3.1.0
info:
  title: Pet Store API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /pets:
    get:
      summary: List pets
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: A list of pets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
      required: [id, name]
      properties:
        id:
          type: integer
        name:
          type: string

Aus dieser einen Datei können Werkzeuge die Dokumentationsseite, einen typisierten Client, ein Server-Stub und einen Mock-Server erzeugen. Das vollständige Format steht in der OpenAPI Specification.

Design-first oder Code-first

• Design-first: Sie schreiben die Beschreibung, stimmen sie mit denen ab, die die API nutzen, und erzeugen dann Stubs und Clients. Frontend-Teams können gegen einen Mock arbeiten (API-Mocking), während das Backend entsteht. Das passt zu einem API-First-Ansatz.
• Code-first: Sie annotieren den Code, und das Framework erzeugt die Beschreibung. Der Start ist schnell, aber die Beschreibung ist nur so genau wie die Annotationen.

Häufige Fehler

• Die Spezifikation von der echten API abweichen lassen. Eine Beschreibung, die niemand prüft, veraltet. Führen Sie Contract-Tests in der CI aus und prüfen Sie die laufende API dagegen.
• Keine Beispiele. Ergänzen Sie example-Werte in den Schemas, damit erzeugte Doku und Mocks brauchbar sind.
• Fehler nicht dokumentiert. Beschreiben Sie 4xx- und 5xx-Antworten, nicht nur 200.
• Falsches Sicherheitsschema. Ist die Authentifizierung falsch beschrieben, scheitern erzeugte Clients und "Try it out" mit 401.
• Als Werkzeug für GraphQL oder gRPC verstehen. OpenAPI beschreibt HTTP-APIs. GraphQL und gRPC haben eigene Schemasprachen.

Swagger, API-Tests und Monitoring

Eine Beschreibung ist nur ein Versprechen über das Verhalten. API-Tests prüfen das Versprechen vor dem Release, API-Monitoring prüft es laufend in Produktion. LoadFocus API Monitoring kann eine OpenAPI-3.x- oder Swagger-2.0-Spezifikation importieren und je Operation einen Monitor erzeugen, mit Prüfungen auf Statuscode, Body, Header und Antwortzeit. Kostenlose Checks laufen alle 5 Minuten.

Dieselbe Beschreibung kann auch Performance-Tests speisen: cURL, HAR, Postman und OpenAPI in Lasttests importieren (auf Englisch) zeigt, wie. Für praktisches Testen von Requests siehe den Leitfaden zum Online-API-Tester (auf Englisch).

Häufige Fragen zu Swagger und OpenAPI

Ist Swagger dasselbe wie OpenAPI?

Nicht ganz. OpenAPI ist die Spezifikation. Swagger ist der ursprüngliche Name dieser Spezifikation und heute der Name der Werkzeuge dazu, etwa Swagger UI und Swagger Editor.

Ist Swagger kostenlos?

Swagger UI und die anderen Open-Source-Werkzeuge sind kostenlos nutzbar. SmartBear verkauft außerdem gehostete Produkte; aktuelle Tarife finden Sie auf deren Website.

Welche Version soll ich nutzen?

Nutzen Sie eine aktuelle 3.x-Version, wenn Ihre Werkzeuge sie unterstützen. Die neueste veröffentlichte Version ist 3.2.1; viele Werkzeuge zielen noch auf 3.0 oder 3.1, prüfen Sie also, was Ihr Doku-Renderer und Codegenerator akzeptieren.

Swagger oder Postman?

Sie erfüllen unterschiedliche Aufgaben. OpenAPI beschreibt die API, Postman ist ein Client zum Erkunden und Testen. Postman kann mit einer OpenAPI-Beschreibung arbeiten.

Kann ich OpenAPI für GraphQL oder gRPC nutzen?

Nein. OpenAPI beschreibt HTTP-APIs. GraphQL nutzt eine eigene Schemasprache und gRPC Protocol Buffers.

Kann ich meine API gegen die Spezifikation testen?

Ja. Contract-Test-Werkzeuge vergleichen echte Antworten mit der Beschreibung, und ein aus der Spezifikation erzeugter Monitor prüft die laufende API nach Zeitplan.