OpenAPI und Swagger sind eng miteinander verbunden und werden oft gemeinsam verwendet, aber sie haben unterschiedliche Rollen.

Was ist OpenAPI?

OpenAPI ist eine Spezifikation, also ein Standard, mit dem man REST-APIs beschreiben kann. Die Beschreibung erfolgt in YAML oder JSON und enthält Informationen wie:

• Welche Endpunkte es gibt (z. B. /benutzer)
• Welche HTTP-Methoden unterstützt werden (GET, POST, etc.)
• Welche Parameter und Antworten erwartet werden
• Welche Authentifizierung nötig ist

Was ist Swagger?

Swagger ist eine Sammlung von Tools, die auf der OpenAPI-Spezifikation basieren. Die wichtigsten Tools sind:

• Swagger Editor: Zum Schreiben und Bearbeiten von OpenAPI-Dokumenten
• Swagger UI: Zeigt die API-Dokumentation im Browser an und erlaubt das direkte Testen
• Swagger Codegen: Erstellt automatisch Code für Clients oder Server aus einer OpenAPI-Datei

Wofür braucht man das?

• Um APIs klar und verständlich zu dokumentieren
• Um Frontend- und Backend-Teams besser abzustimmen
• Um automatisch Code zu generieren (z. B. für SDKs)
• Um APIs zu testen, auch wenn sie noch nicht vollständig implementiert sind
• Um Fehler frühzeitig zu erkennen und zu vermeiden

Solche API-Dokumentationen können auch automatisch, z.B. mittels Annotationen im Code, erzeugt werden:

Vorteile:

• Schnell und bequem: Du schreibst nur den Code (z. B. Controller, DTOs), und die OpenAPI-Dokumentation wird automatisch erstellt.
• Immer aktuell: Änderungen im Code wirken sich direkt auf die API-Dokumentation aus.
• Weniger Fehleranfällig: Kein Risiko, dass Dokumentation und Implementierung auseinanderlaufen.

Typische Tools:

• Quarkus: Nutzt quarkus-smallrye-openapi, um automatisch OpenAPI-Dokumente zu erzeugen.
• Spring Boot: Mit springdoc-openapi oder Swagger-Annotations.
• NestJS: Mit @nestjs/swagger.