Swagger-Kernkomponenten
Swagger ist ein Open-Source-Toolset, das rund um die OpenAPI-Spezifikation aufgebaut ist und zum Entwerfen, Erstellen, Dokumentieren und Verwenden von RESTful-APIs dient.
Swagger bietet eine standardisierte Möglichkeit, die Struktur von APIs zu beschreiben, sodass sowohl Entwickler als auch Maschinen die Funktionalität einer API verstehen können, ohne auf Quellcode oder andere Dokumentation zuzugreifen.
Die Kernwerte von Swagger sind:
- Standardisierung: Bietet ein einheitliches API-Beschreibungsformat
- Visualisierung: Generiert automatisch interaktive API-Dokumentation
- Testbarkeit: Ermöglicht das Testen von API-Endpunkten direkt in der Dokumentation
- Codegenerierung: Unterstützt client- und serverseitige Codegenerierung in mehreren Sprachen
Swagger-Kernkomponenten
| Komponente | Eingabe | Ausgabe | Anwendbare Phase |
|---|---|---|---|
| Swagger Editor | YAML/JSON manuell schreiben | API-Dokumentation mit Echtzeitvorschau | API-Designphase |
| Swagger UI | OpenAPI-Datei | Interaktive Web-Dokumentation | Entwicklungs-/Testphase |
| Swagger Codegen | OpenAPI-Datei | Client-/Server-Code | Phase der Frontend-Backend-Zusammenarbeit |
Flussdiagramm zur Komponenten-Zusammenarbeit:
Swagger Editor(设计API) ↓ OpenAPI 规范文件(YAML/JSON) ↓ Swagger UI(展示文档) 或 Swagger Codegen(生成代码)

Swagger-Kernkomponenten erklärt
1. Swagger Editor
Swagger Editor ist ein browserbasierter visueller Editor zum Schreiben und zur Echtzeitvorschau von OpenAPI-Spezifikationen (YAML/JSON-Format).
Swagger Editor bietet Syntaxhervorhebung, Autovervollständigung und Fehlervalidierung.
Die Codegenerierungs-, Speicher- und Exportfunktionen von Swagger Editor wurden jetzt in SmartBear API Hub integriert. Zugriffsadresse:https://try.platform.smartbear.com/new-organization。
Anwendungsfälle:
- API-Prototypen schnell entwerfen
- Syntax der OpenAPI-Spezifikation lernen
Den Online-Editor Swagger Editor aufrufen:https://editor.swagger.io/
Geben Sie den folgenden YAML-Code ein (definiert einen einfachen GET /users-Endpunkt):
Beispiel
openapi: 3.0.3
Info:
title: BEISPIEL Benutzerverwaltungssystem
version: 1.0.0
paths:
/users:
get:
summary: Benutzerliste abrufen
responses:
'200':
description: Gibt die Benutzerliste erfolgreich zurück
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
Auf der rechten Seite werden die API-Dokumentation und die interaktive Benutzeroberfläche in Echtzeit gerendert.

Swagger UI
Swagger UI wandelt OpenAPI-Spezifikationen in visuelle interaktive Dokumentation um und unterstützt das Testen von APIs direkt im Browser.
Swagger UI generiert automatisch Anfragebeispiele, Antwortmodelle und eine Debugging-Schnittstelle.
Swagger UI: https://swagger.io/tools/swagger-ui/
Anwendungsfälle:
- API-Dokumentation im Team teilen
- Frontend-Entwickler debuggen APIs
Integrationsbeispiel (mit Node.js), Abhängigkeiten installieren:
npm install swagger-ui-express swagger-jsdoc
Erstellen Sie eine swagger.js-Konfigurationsdatei:
Beispiel
const options = {
Definition: {
openapi: '3.0.0',
info: { title: 'Benutzer-API', version: '1.0.0' },
},
apis: ['./routes/*.js'], // Kommentare in Routendateien scannen
};
const swaggerSpec = swaggerJSDoc(options);
module.exports = swaggerSpec;
UI in Express einbinden:
Beispiel
const swaggerUi = require('swagger-ui-express');
const swaggerSpec = require('./swagger');
const app = express();
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
Besuchen Sie http://localhost:3000/api-docs, um die Dokumentation anzuzeigen.

Swagger Codegen
Swagger Codegen generiert automatisch Client-SDKs (z. B. Java, Python) oder Server-Stub-Code (z. B. Spring, Flask) basierend auf OpenAPI-Spezifikationen.
Swagger Codegen unterstützt benutzerdefinierte Vorlagen.
Downloadseite:https://swagger.io/tools/swagger-codegen/
Anwendungsfälle:
- Client-Code für API-Aufrufe schnell generieren
- Automatisierte Entwicklung serverseitiger Schnittstellen
Anwendungsbeispiel (Java-Client über die Befehlszeile generieren), Swagger Codegen CLI herunterladen:
wget https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/3.0.35/swagger-codegen-cli-3.0.35.jar -O swagger-codegen-cli.jar
Code generieren:
java -jar swagger-codegen-cli.jar generate \ -i https://petstore.swagger.io/v2/swagger.json \ -l java \ -o ./petstore-api-client
Swagger Hub (optionale Erweiterung)
Swagger Hub ist Swaggers Cloud-Plattform und bietet kollaboratives Design, Versionsverwaltung und gehostete Dokumentation.
Swagger Hub unterstützt Teamzusammenarbeit und API-Lebenszyklusverwaltung.
Anwendungsfälle:
- API-Projektmanagement auf Unternehmensebene
- Verteilte Teams, die Online-Zusammenarbeit benötigen
Zugriffsadresse:https://swagger.io/api-hub/
Weitere Erweiterungen