Swagger / OpenAPI
Swagger / OpenAPI ist der Industriestandard für API-Dokumentation — maschinenlesbare API-Beschreibungen ermöglichen automatische Client-Generierung und interaktive Dokumentation.
OpenAPI (früher Swagger) definiert ein JSON/YAML-Format zur Beschreibung von REST-APIs. Swagger UI rendert daraus interaktive Dokumentation mit 'Try it out'-Funktion. Codegen-Tools generieren typisierte API-Clients für TypeScript, Python, Java und mehr automatisch. NestJS integriert Swagger über Dekoratoren.
Swagger / OpenAPI bei SW Business Solutions
Swagger UI und OpenAPI-Spezifikationen sind bei SW Business Solutions Pflichtbestandteile jeder API. Wir dokumentieren alle Endpunkte vollständig mit Swagger-Dekoratoren in NestJS.
Einsatz in Kundenprojekten
- NestJS Swagger: @ApiTags, @ApiOperation, @ApiResponse und @ApiProperty in jedem Controller und DTO
- Swagger UI: Interaktive API-Dokumentation unter /api - direktes Testen im Browser
- OpenAPI-Export: JSON/YAML-Spec als Basis für Code-Generierung und Contract-Testing
- API-Versionierung: Swagger dokumentiert v1 und v2 parallel
Pflichtannotationen bei SW Business Solutions:
- Jeder Controller: @ApiTags
- Jede Methode: @ApiOperation mit summary
- Alle Response-Typen: @ApiResponse mit Status-Code und DTO
- Alle DTO-Felder: @ApiProperty mit Typ und Beispielwert
Warum vollständige Swagger-Dokumentation?
- Onboarding: Neue Entwickler verstehen die API ohne Quellcode-Lektüre
- Frontend-Autonomie: Frontend-Entwickler können gegen Swagger-Spec entwickeln
- Contract-Tests: OpenAPI als Basis für automatisierte Contract-Tests
- Kundentransparenz: Kunden sehen alle API-Möglichkeiten direkt
Typische Projektkombinationen
| Kombination | Anwendungsfall |
|---|---|
| Swagger + NestJS | Automatische API-Dokumentation |
| Swagger + Postman | Collection aus Swagger generiert |
| Swagger + TypeScript-Codegen | Type-safe API-Client |
| Swagger + CI/CD | Spec-Änderungen als Breaking-Change-Detection |
Technical Details
OpenAPI 3.1 ist die aktuelle Version und aligns mit JSON Schema Draft 2020-12. Swagger Editor validiert OpenAPI-Spezifikationen in Echtzeit. Postman kann OpenAPI-Collections importieren. Spectral linted OpenAPI-Specs nach eigenen Regeln.
Why Swagger / OpenAPI?
Use Cases for Swagger / OpenAPI
API Documentation
Automatically generated, always up-to-date Swagger UI documentation for developers and teams.
Client Generation
Automatically generate TypeScript, Python and Java clients from the OpenAPI spec.
API Design
Design-first API development: write spec before code for clear frontend-backend contract.
API Testing
Swagger UI as interactive test client for quick API testing without Postman.
Frequently Asked Questions about Swagger / OpenAPI
Was ist der Unterschied zwischen Swagger und OpenAPI?
Wie generiere ich OpenAPI-Clients automatisch?
Code-First oder Design-First?
OpenAPI 3.0 oder 3.1?
Quick Facts
Interested in Swagger / OpenAPI?
Request consultationUsed in these projects
SW Business Solutions Platform
Komplette Unternehmensplattform mit CMS-Backend, öffentlicher Firmenwebsite und Admin-Dashboard — entwickelt als Git-Submodul-Architektur mit drei eigenständigen Repositories.
SWBS Backend API
NestJS 11 REST-API mit Fastify-Adapter als CMS-Backend für alle drei SWBS-Anwendungen.
Blog articles about Swagger / OpenAPI
Interested in Swagger / OpenAPI?
Let us discuss together how Swagger / OpenAPI can be used in your next project.