Ihr erstes Swagger-Dokument schreiben

Swagger (OpenAPI) ist eine Spezifikation und ein Toolset zum Beschreiben, Generieren und Visualisieren von RESTful-Webdiensten.

Nachfolgend beschreibe ich ausführlich, wie Sie Ihr erstes Swagger-Dokument von Grund auf schreiben.

Swagger-Dokumente verwenden hauptsächlich das YAML- oder JSON-Format und definieren verschiedene Aspekte der API, darunter:

  • Grundlegende API-Informationen (Titel, Version usw.)
  • Verfügbare Pfade und Operationen
  • Eingabeparameter und Ausgabeantworten
  • Authentifizierungsmethoden
  • Datenmodelldefinitionen

Erstellungsschritte

1. Grundlegende Dateistruktur erstellen

Erstellen Sie zunächst eine Datei namensswagger.yamloderswagger.jsonfile. Dieses Tutorial verwendet YAML-Format als Beispiel, da es einfacher zu lesen und zu schreiben ist.

Beispiel
openapi: 3.0.0
Info:
  title:Meine erste API
  description:Dies ist ein einfaches API-Beispieldokument
  version: 1.0.0
  contact:
    name:API-Support-Team
    email: support@example.com
    url: https://www.example.com/support
servers:
  - url: https://api.example.com/v1
    description:Produktionsumgebung
  - url: https://dev-api.example.com/v1
    description:Entwicklungsumgebung

2. Grundlegende Dokumentinformationen hinzufügen

Beispiel
openapi: 3.0.0
Info:
  title:Meine erste API
  description:Dies ist ein einfaches API-Beispieldokument
  version: 1.0.0
  contact:
    name:API-Support-Team
    email: support@example.com
    url: https://www.example.com/support
servers:
  - url: https://api.example.com/v1
    description:Produktionsumgebung
  - url: https://dev-api.example.com/v1
    description:Entwicklungsumgebung

3. Pfade und Operationen definieren

Pfade definieren die Endpunkte, auf die die API zugreifen kann, und Operationen definieren die HTTP-Methoden (GET, POST, PUT, DELETE usw.), die auf diesen Endpunkten ausgeführt werden können.

Beispiel
paths:
  /users:
    get:
      summary:Liste aller Benutzer abrufen
      description:Gibt alle Benutzerinformationen im System zurück
      operationId: getUsers
      parameters:
        - name: limit
          in: query
          description:Maximale Anzahl der zurückgegebenen Ergebnisse
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 20
      responses:
        '200':
          description:Benutzerliste erfolgreich abgerufen
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '400':
          description:Ungültige Anfrage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      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'
      responses:
        '201':
          description:Benutzer erfolgreich erstellt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description:Ungültige Anfrage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

4. Komponenten und Modelle definieren

IncomponentsDieser Abschnitt definiert wiederverwendbare Modelle:

Beispiel
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
   
    NewUser:
      type: object
      properties:
        username:
          type: string
          description:Benutzername
        email:
          type: string
          format: email
          description:Benutzer-E-Mail
        Passwort:
          type: string
          format: password
          description:Benutzerpasswort
          minLength: 8
      required:
        - username
        - email
        - Passwort
   
    Fehler:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
      required:
        - code
        - message

5. Sicherheitsdefinitionen hinzufügen

Definieren Sie die Sicherheitsanforderungen der API:

Beispiel
Sicherheit:
  - bearerAuth: []

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

6. Vollständiges Dokumentbeispiel

Kombinieren Sie alle oben genannten Abschnitte, und Sie erhalten ein vollständiges Swagger-Dokument.

Beispiel

openapi: 3.0.0
Info:
  title:Meine erste API
  description:Dies ist ein einfaches API-Beispieldokument
  version: 1.0.0
  contact:
    name:API-Support-Team
    email: support@example.com
    url: https://www.example.com/support
servers:
  - url: https://api.example.com/v1
    description:Produktionsumgebung
  - url: https://dev-api.example.com/v1
    description:Entwicklungsumgebung

paths:
  /users:
    get:
      summary:Liste aller Benutzer abrufen
      description:Gibt alle Benutzerinformationen im System zurück
      operationId: getUsers
      parameters:
        - name: limit
          in: query
          description:Maximale Anzahl der zurückgegebenen Ergebnisse
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 20
      responses:
        '200':
          description:Benutzerliste erfolgreich abgerufen
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '400':
          description:Ungültige Anfrage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      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'
      responses:
        '201':
          description:Benutzer erfolgreich erstellt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description:Ungültige Anfrage
          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

    NewUser:
      type: object
      properties:
        username:
          type: string
          description:Benutzername
        email:
          type: string
          format: email
          description:Benutzer-E-Mail
        Passwort:
          type: string
          format: password
          description:Benutzerpasswort
          minLength: 8
      required:
        - username
        - email
        - Passwort

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

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

Sicherheit:
  - bearerAuth: []

7. Swagger-Tools verwenden

Es gibt mehrere Möglichkeiten, Ihr Swagger-Dokument zu visualisieren und zu testen:

  1. Swagger UI: eine interaktive Dokumentationsseite
  2. Swagger Editor: ein Online-Editor, der das Dokument in Echtzeit als Vorschau anzeigen kann
  3. Swagger Codegen: ein Tool zum Generieren von Client-Code

8. Testen Sie Ihr Dokument online

Sie könnenSwagger Editorverwenden, um Ihr Dokument online zu testen. Kopieren Sie einfach Ihr YAML oder JSON in den Editor, und im rechten Bereich wird ein visuelles API-Dokument angezeigt.

9. Bewährte Vorgehensweisen

  • Aussagekräftige Operations-IDs verwenden
  • Detaillierte Beschreibungen für jeden Endpunkt angeben
  • Stellen Sie sicher, dass alle Parameter Beschreibungen haben
  • Dokumentieren Sie alle möglichen Antwort-Statuscodes
  • Modellreferenzen verwenden, um Duplizierung zu reduzieren
  • Halte das Dokument aktuell
  • Füge Beispielanfragen und -antworten für jeden Endpunkt hinzu

10. Häufige Parameterorte

Swagger definiert mehrere Parameterorte:

  • path: Parameter im URL-Pfad, wie z. B./users/{id}
  • query: URL-Abfrageparameter, wie z. B./users?limit=10
  • header: HTTP-Header-Parameter
  • cookie: Cookie-Parameter
  • body: Request-Body-Parameter (in OpenAPI 3.0 wird stattdessen requestBody verwendet)

11. Erweitere dein Dokument

Wenn sich deine API weiterentwickelt, erweitere dein Swagger-Dokument fortlaufend:

  • Füge weitere Endpunkte hinzu
  • Zusätzliche Modelle definieren
  • Detailliertere Beschreibungen hinzufügen
  • Anfrage- und Antwortbeispiele hinzufügen

12. Integration in die reale Entwicklung

In der realen Entwicklung können Sie:

  • Swagger in Ihren Code integrieren
  • Tools zur automatischen Generierung verwenden
  • Dokumentation aus Codekommentaren generieren
  • Swagger UI in Ihre Anwendung einbetten
Weitere Erweiterungen