Swagger-Dokumentationsbeispiel

Das Folgende ist ein vollständiges Beispiel eines Swagger-Dokuments, das eine detaillierte Spezifikation einer API für ein Benutzerverwaltungssystem ist.

Dieses Dokument beschreibt die API eines Benutzerverwaltungssystems, einschließlich grundlegender Benutzerinformationen, Authentifizierungsdienste, Datenmodelle usw.

Diese API folgt dem RESTful-Stil und verwendet das JSON-Format für den Datenaustausch.

Sie können den Swagger Editor verwenden, um Ihr Dokument online zu testen. Online-Adresse:https://editor.swagger.io/. Kopieren Sie einfach Ihr YAML oder JSON und fügen Sie es in den Editor ein, und das rechte Panel zeigt die visualisierte API-Dokumentation an.

Beispiel

openapi: 3.0.0
Info:
title:Meine erste API
description: |
Dies ist ein einfaches API-Beispieldokument, das die grundlegenden Funktionen eines Benutzerverwaltungssystems demonstriert.
Einschließlich Benutzerabfrage, -erstellung, -aktualisierung und -löschung.
version: 1.0.0
contact:
name:API-Support-Team
email: support@example.com
url: https://www.example.com/support
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html

servers:
- url: https://api.example.com/v1
description:Produktionsumgebung
- url: https://staging-api.example.com/v1
description:Staging-Umgebung
- url: https://dev-api.example.com/v1
description:Entwicklungsumgebung

tags:
- name:Benutzer
description:Operationen zur Benutzerverwaltung
- name:Authentifizierung
description:Operationen zur Authentifizierung

paths:
/users:
get:
tags:
-Benutzer
summary:Liste aller Benutzer abrufen
description:Gibt alle Benutzerinformationen im System zurück, mit Unterstützung für Paginierung und Filterung
operationId: getUsers
parameters:
- name: limit
in: query
description:Maximale Anzahl der zurückzugebenden Ergebnisse
required: false
schema:
type: integer
format: int32
minimum: 1
maximum: 100
default: 20
- name: offset
in: query
description:Paginierungsoffset
required: false
schema:
type: integer
format: int32
minimum: 0
default: 0
- name: status
in: query
description:Nach Benutzerstatus filtern
required: false
schema:
type: string
enum: [active, inactive, banned]
responses:
'200':
description:Benutzerliste erfolgreich abgerufen
content:
application/json:
schema:
type: object
properties:
total:
type: integer
description:Gesamtzahl der Benutzer
users:
type: array
items:
$ref: '#/components/schemas/User'
example:
total: 2
users:
- id: 1
username: "john_doe"
email: "[email protected]"
status: "active"
createdAt: "2023-05-01T12:00:00Z"
- id: 2
username: "jane_smith"
email: "[email protected]"
status: "active"
createdAt: "2023-05-02T14:30:00Z"
'400':
description:Ungültige Anfrage
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
$ref: '#/components/responses/UnauthorizedError'
Sicherheit:
- bearerAuth: []

post:
tags:
-Benutzer
summary:Einen neuen Benutzer erstellen
description:Einen neuen Benutzer im System erstellen
operationId: createUser
requestBody:
description:Benutzerinformationen
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NewUser'
example:
username: "new_user"
email: "[email protected]"
password: "securePassword123"
responses:
'201':
description:Benutzer erfolgreich erstellt
content:
application/json:
schema:
$ref: '#/components/schemas/User'
example:
id: 3
username: "new_user"
email: "[email protected]"
status: "active"
createdAt: "2023-05-10T09:15:00Z"
'400':
description:Ungültige Anfrage
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 400
message: "Ungültiges E-Mail-Format"
'409':
description:Ressourcenkonflikt
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 409
message: "Benutzername existiert bereits"
'401':
$ref: '#/components/responses/UnauthorizedError'
Sicherheit:
- bearerAuth: []

/users/{userId}:
parameters:
- name: userId
in: path
description:Benutzer-ID
required: true
schema:
type: integer
format: int64

get:
tags:
-Benutzer
summary:Einen bestimmten Benutzer abrufen
description:Detaillierte Informationen zu einem bestimmten Benutzer anhand der ID abrufen
operationId: getUserById
responses:
'200':
description:Benutzerinformationen erfolgreich abgerufen
content:
application/json:
schema:
$ref: '#/components/schemas/UserDetail'
example:
id: 1
username: "john_doe"
email: "[email protected]"
firstName: "John"
lastName: "Doe"
phone: "+1234567890"
status: "active"
createdAt: "2023-05-01T12:00:00Z"
lastLogin: "2023-05-10T08:30:00Z"
'404':
description:Benutzer nicht gefunden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 404
message: "Benutzer nicht gefunden"
'401':
$ref: '#/components/responses/UnauthorizedError'
Sicherheit:
- bearerAuth: []

put:
tags:
-Benutzer
summary:Benutzerinformationen aktualisieren
description:Informationen eines bestimmten Benutzers aktualisieren
operationId: updateUser
requestBody:
description:Aktualisierte Benutzerinformationen
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateUser'
example:
firstName: "Jonathan"
lastName: "Doe"
phone: "+1987654321"
responses:
'200':
description:Benutzerinformationen erfolgreich aktualisiert
content:
application/json:
schema:
$ref: '#/components/schemas/UserDetail'
'400':
description:Ungültige Anfrage
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description:Benutzer nicht gefunden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
$ref: '#/components/responses/UnauthorizedError'
Sicherheit:
- bearerAuth: []

Löschen:
tags:
-Benutzer
summary:Benutzer löschen
description:Löscht einen bestimmten Benutzer aus dem System
operationId: deleteUser
responses:
'204':
description:Benutzer erfolgreich gelöscht
'404':
description:Benutzer nicht gefunden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
$ref: '#/components/responses/UnauthorizedError'
Sicherheit:
- bearerAuth: []

/auth/login:
post:
tags:
-Authentifizierung
summary:Benutzeranmeldung
description:Benutzer meldet sich an und erhält ein Zugriffstoken
operationId: login
requestBody:
description:Anmeldedaten
required: true
content:
application/json:
schema:
type: object
properties:
username:
type: string
description:Benutzername
Passwort:
type: string
format: password
description:Passwort
required:
- username
- Passwort
example:
username: "john_doe"
password: "password123"
responses:
'200':
description:Anmeldung erfolgreich
content:
application/json:
schema:
type: object
properties:
accessToken:
type: string
description:JWT-Zugriffstoken
tokenType:
type: string
description:Tokentyp
expiresIn:
type: integer
description:Ablaufzeit des Tokens (Sekunden)
example:
accessToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
tokenType: "Bearer"
expiresIn: 3600
'401':
description:Anmeldung fehlgeschlagen
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 401
message: "Falscher Benutzername oder falsches Passwort"

/auth/register:
post:
tags:
-Authentifizierung
summary:Benutzerregistrierung
description:Neuen Benutzer registrieren und ein Zugriffstoken abrufen
operationId: register
requestBody:
description:Registrierungsinformationen
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NewUser'
responses:
'201':
description:Registrierung erfolgreich
content:
application/json:
schema:
type: object
properties:
user:
$ref: '#/components/schemas/User'
accessToken:
type: string
description:JWT-Zugriffstoken
example:
user:
id: 3
username: "new_user"
email: "[email protected]"
status: "active"
createdAt: "2023-05-10T09:15:00Z"
accessToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
'400':
description:Ungültige Anfrage
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description:Benutzer existiert bereits
content:
application/json:
schema:
$ref: '#/components/schemas/Error'

components:
schemas:
Benutzer:
type: object
properties:
id:
type: integer
format: int64
description:Eindeutige Benutzerkennung
username:
type: string
description:Benutzername
email:
type: string
format: email
description:Benutzer-E-Mail
status:
type: string
enum: [active, inactive, banned]
description:Benutzerstatus
createdAt:
type: string
format: date-time
description:Erstellungszeit
required:
- id
- username
- email
- status

UserDetail:
allOf:
- $ref: '#/components/schemas/User'
- type: object
properties:
firstName:
type: string
description:Vorname
lastName:
type: string
description:Nachname
phone:
type: string
description:Telefonnummer
lastLogin:
type: string
format: date-time
description:Letzte Anmeldezeit

NewUser:
type: object
properties:
username:
type: string
description:Benutzername
minLength: 3
maxLength: 50
email:
type: string
format: email
description:Benutzer-E-Mail
Passwort:
type: string
format: password
description:Benutzerpasswort
minLength: 8
maxLength: 100
firstName:
type: string
description:Vorname
lastName:
type: string
description:Nachname
phone:
type: string
description:Telefonnummer
required:
- username
- email
- Passwort

UpdateUser:
type: object
properties:
email:
type: string
format: email
description:Benutzer-E-Mail
firstName:
type: string
description:Vorname
lastName:
type: string
description:Nachname
phone:
type: string
description:Telefonnummer
Passwort:
type: string
format: password
description:Neues Passwort (falls geändert)
minLength: 8
maxLength: 100

Fehler:
type: object
properties:
code:
type: integer
format: int32
description:Fehlercode
message:
type: string
description:Fehlermeldung
required:
- code
- message

responses:
UnauthorizedError:
description:Zugriffstoken fehlt oder ist ungültig
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 401
message: "Unberechtigter Zugriff"

securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description:Authentifizierung mittels JWT Bearer Token

Sicherheit:
- bearerAuth: []

Die folgenden sind die Hauptkomponenten des Dokuments:

1. Abschnitt mit Basisinformationen

API-Titel und -Beschreibung: Grundfunktionen des Benutzerverwaltungssystems
Versionsinformationen：1.0.0
Kontaktinformationen: Kontaktinformationen des API-Support-Teams
Lizenz：Apache 2.0

2. Serverkonfiguration

Produktionsumgebung
Staging-Umgebung
Entwicklungsumgebung

3. API-Tag-Klassifizierung

Benutzerbezogene Operationen
Authentifizierungsbezogene Operationen

4. Pfade und Operationen

Diese API umfasst die folgenden Endpunkte:

Benutzerverwaltung

GET /users- Liste aller Benutzer abrufen (unterstützt Paginierung und Filterung)
POST /users- Einen neuen Benutzer erstellen
GET /users/{userId}- Details eines bestimmten Benutzers abrufen
PUT /users/{userId}- Benutzerinformationen aktualisieren
DELETE /users/{userId}- Benutzer löschen

Authentifizierungsdienst

POST /auth/login- Benutzeranmeldung
POST /auth/register- Benutzerregistrierung

5. Datenmodelle

User- Grundlegende Benutzerinformationen
UserDetail- Detaillierte Benutzerinformationen
NewUser- Request-Body zum Erstellen eines Benutzers
UpdateUser- Anfragekörper zum Aktualisieren eines Benutzers
Error- Fehlerantwort

6. Sicherheitsdefinitionen

Verwenden Sie JWT Bearer Token für die API-Authentifizierung.

Dieses Dokument folgt der OpenAPI-3.0.0-Spezifikation und enthält vollständige Anfrageparameter, Antwort-Statuscodes, Datenmodelldefinitionen und Beispielwerte. Sie können dieses YAML-Dokument in den Swagger Editor kopieren, um die Visualisierung zu sehen, oder es in Ihr Projekt integrieren.

Dieses Dokument kann als Grundlage für Ihre RESTful-API-Entwicklung dienen und kann im Laufe des Projekts weiter erweitert und verbessert werden.

Andere Erweiterungen