Blog

API mit Swagger dokumentieren

  • Beitrags-Autor:
  • Beitrags-Kategorie:Sonstiges

Swagger Editor

Beispiel „openapi.yaml“:

openapi: 3.0.4
info:
  title: Demo API
  version: 1.0.0

servers:
  - url: https://c-intact.d-velop.cloud/scripting/script/09399c54-15a4-4ea5-af4c-6ed1208bd07c/run
  - url: https://webhook.site/2d8ba29a-87ca-49ff-bc97-b265f3bc089f

tags:
  - name: aeink
    description: Einkaufsakte
  - name: averk
    description: Verkaufsakte

paths:
  /aeinkByAnfnr:
    post:
      tags:
        - aeink
      summary: Erstellt eine Einkaufsakte zur EK-Anfragenummer.
      description: sucht "ekanfnr", ohne Treffer wird Akte mit allen Eigenschaften angelegt
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - ekanfnr
                - anfbez
              properties:
                liefnr:
                  type: string
                  example: "1001"
                liefname:
                  type: string
                  example: "Mustermann AG"
                ekabt:
                  type: string
                  example: "Einkauf"
                ekanfnr:
                  type: string
                  example: "A260001"
                anfbez:
                  type: string
                  example: "Demo-Anfrage"
      responses:
        "200":
          description: Erfolgreich
        "400":
          description: Bad Request
      security:
        - AnmeldungDemoApi: []
    put:
      tags:
        - aeink
      summary: Aktualisiert eine Einkaufsakte über die EK-Anfragenummer.
      description: gesucht wird "ekanfnr", bei Treffer werden alle optionalen Felder überschrieben
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - ekanfnr
              properties:
                liefnr:
                  type: string
                  example: "1001"
                liefname:
                  type: string
                  example: "Mustermann AG"
                ekabt:
                  type: string
                  example: "Einkauf"
                ekanfnr:
                  type: string
                  example: "A260001"
                anfbez:
                  type: string
                  example: "Demo-Anfrage"
      responses:
        "200":
          description: Erfolgreich
        "400":
          description: Bad Request
      security:
        - AnmeldungDemoApi: []
  /aeinkByBestnr:
    post:
      tags:
        - aeink
      summary: Erstellt eine Einkaufsakte für die eigene Bestellnummer.
      description: Bestellnummer aus LN, nicht Bestellnummer vom Lieferanten, optionale Felder werden ggf. leer verwendet; sucht "bestnr", ohne Treffer wird Akte mit allen Eiegenschaften angelegt
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - bestnr
              properties:
                liefnr:
                  type: string
                  example: "1001"
                liefname:
                  type: string
                  example: "Mustermann AG"
                ekabt:
                  type: string
                  example: "Einkauf"
                bestnr:
                  type: string
                  example: "B260001"
      responses:
        "200":
          description: Erfolgreich
        "400":
          description: Bad Request
      security:
        - AnmeldungDemoApi: []
    put:
      tags:
        - aeink
      summary: Aktualisiert eine Einkaufsakte über die eigene Bestellnummer.
      description: gesucht wird "bestnr", bei Treffer werden alle optionalen Felder überschrieben
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - bestnr
              properties:
                liefnr:
                  type: string
                  example: "1001"
                liefname:
                  type: string
                  example: "Mustermann AG"
                ekabt:
                  type: string
                  example: "Einkauf"
                bestnr:
                  type: string
                  example: "B260001"
      responses:
        "200":
          description: Erfolgreich
        "400":
          description: Bad Request
      security:
        - AnmeldungDemoApi: []

components:
  securitySchemes:
    AnmeldungDemoApi:
      type: apiKey
      in: header
      name: x-demo-key
Schlagwörter: