Erweiterte Swagger-Funktionen

Verwenden von components zur Wiederverwendung von Definitionen

Schema-Wiederverwendung (Datenmodell)

components ermöglichen es Ihnen, Elemente zu definieren, die in der gesamten API-Dokumentation wiederverwendet werden können, wodurch Duplizierung reduziert und Konsistenz sichergestellt wird:

Beispiel

components:
  schemas:
    Benutzer:
      type: object
      properties:
        id:
          type: integer
          format: int64
        username:
          type: string
        email:
          type: string

Referenzmethode:

Beispiel

paths:
  /users/{id}:
    get:
      responses:
        '200':
          description:Benutzerinformationen
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

Wiederverwendung von Parametern (gemeinsame Parameter)

Gemeinsame Parameter definieren:

Beispiel

components:
  parameters:
    PageParam:
      name: page
      in: query
      schema:
        type: integer
        default: 1
      description:Seitennummer
    LimitParam:
      name: limit
      in: query
      schema:
        type: integer
        default: 10
      description:Datensätze pro Seite

Referenzmethode:

Beispiel

paths:
  /products:
    get:
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'

Wiederverwendung von Antworten (gemeinsame Antworten)

Standardantworten definieren:

Beispiel

components:
  responses:
    NotFound:
      description:Ressource nicht gefunden
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
                example: 404
              message:
                type: string
                example: "Ressource existiert nicht"
    BadRequest:
      description:Fehler beim Anfrageparameter
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
                example: 400
              message:
                type: string

Referenzmethode:

Beispiel

paths:
  /users/{id}:
    get:
      responses:
        '200':
          description:Erfolg
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          $ref: '#/components/responses/NotFound'
        '400':
          $ref: '#/components/responses/BadRequest'

API-Versionskontrolle

Versionen über Server unterscheiden

Beispiel

servers:
  - url: https://api.example.com/v1
    description: API v1
  - url: https://api.example.com/v2
    description: API v2

Versionen anhand des Pfads unterscheiden

Beispiel

paths:
  /v1/users:
    get:
# v1 Benutzeroberfläche...
 
  /v2/users:
    get:
# v2 Benutzeroberfläche...

Versionen anhand von Anfrage-Headern unterscheiden

Beispiel

paths:
  /users:
    get:
      parameters:
        - name: api-version
          in: header
          required: true
          schema:
            type: string
            enum: ['1.0', '2.0']

Mock-Daten-Simulation

Beispiele verwenden, um Beispieldaten zu definieren

Beispiele in der Antwort definieren:

Beispiel

paths:
  /users:
    get:
      responses:
        '200':
          description:Benutzerliste
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
              examples:
                userList:
                  summary:Beispiel-Benutzerliste
                  value:
                    - id: 1
                      username: "user1"
                      email: "[email protected]"
                    - id: 2
                      username: "user2"
                      email: "[email protected]"

Verwenden der Swagger UI Mock-Funktion

Swagger UI integriert einen Mock-Server, der Mock-Antworten basierend auf Ihrer OpenAPI-Definition generieren kann.

Konfigurieren Sie mockServer in Swagger UI:

Beispiel

SwaggerUI({
  url: "https://petstore.swagger.io/v2/swagger.json",
  dom_id: '#swagger-ui',
  presets: [
    SwaggerUI.presets.apis,
    SwaggerUIStandalonePreset
  ],
  plugins: [
    SwaggerUI.plugins.MockPlugin
  ],
  mockImplementations: {
    '/users': {
      get: () => ({
        status: 200,
        body: [
          { id: 1, name: "Test User 1" },
          { id: 2, name: "Test User 2" }
        ]
      })
    }
  }
})

Verwendung von Mock-Diensten von Drittanbietern

  • Prism: OpenAPI-Mock-Server
  • Mockoon: ein Mock-API-Tool, das mit Swagger integriert werden kann
  • Postman: bietet Mock-Server-Funktionalität

Erweiterte Sicherheitskonfiguration

Definieren Sie mehrere Authentifizierungsmethoden:

Beispiel

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
    OAuth2:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://example.com/oauth/authorize
          scopes:
            read:Leseberechtigung
            write:Schreibberechtigung

Sicherheitsdefinitionen anwenden:

Beispiel

Sicherheit:
  - bearerAuth: []
  - apiKeyAuth: []

paths:
  /users:
    get:
      Sicherheit:
        - OAuth2: [read]

Dokumententrennung und -organisation

Verwenden Sie$refzum Referenzieren externer Dateien:

Beispiel

paths:
  /users:
    $ref: './paths/users.yaml'
  /products:
    $ref: './paths/products.yaml'

components:
  schemas:
    Benutzer:
      $ref: './schemas/user.yaml'

Tags und Gruppierung

Verwenden Sie Tags, um API-Endpunkte zu organisieren:

Beispiel

tags:
  - name: users
    description:Benutzerverwaltung
  - name: products
    description:Produktverwaltung

paths:
  /users:
    get:
      tags:
        - users
  /products:
    get:
      tags:
        - products

Erweiterungsfelder

Durchx-benutzerdefinierte Eigenschaften mit einem Präfix hinzufügen:

Beispiel

lpaths:
  /users:
    get:
      x-controller: UserController
      x-rate-limit: 100
      x-deprecated: false

Diese erweiterten Funktionen können Ihnen helfen, strukturiertere, wartbarere und professionellere API-Dokumentation zu erstellen.

Andere Erweiterungen