openapi: "3.0.3"

info:
  title: SLT Vereinsportal
  version: 0.1.0
  contact:
    name: Christian Wolf
    email: homepage@slt.wolf-stuttgart.net
  description: |

#externalDocs:

servers:
  - description: Production Server
    url: https://www.tanzen-slt.de/public/internal/api
  - description: Local test environment
    url: http://localhost:80/internal/api

components:
  
  securitySchemes:
    jwt:
      type: http
      scheme: bearer
      
  responses:
    notAuth:
      description: Es ist kein Benutzer eingeloggt.
    error:
      description: Es ist ein Fehler aufgetreten.
      content:
        application/json:
          schema:
            type: object
            properties:
              errCode:
                type: integer
                description: Ein numerischer Fehlercode zur automatischen Verarbeitung
                example: 3
              msg:
                type: string
                description: Eine menschlich lesbare Fehlermeldung
                example: Der Eintrag existiert nicht
              failure:
                type: boolean
                example: true
                description: true, wenn es sich um einen Fehler handelt.
            required:
              - errCode
              - msg
              - failure
    notAllowed:
      description: Nicht berechtigt
      content:
        application/json:
          schema:
            type: object
            properties:
              errorCode:
                type: integer
                example: 1
              description:
                type: string
                example: Sie sind nicht berechtigt diese Information abzurufen
              failure:
                type: boolean
                example: true
            required:
              - errorCode
              - description
              - failure
    ok:
      description: OK.
      #content:
        #application/json:
          #schema:
            #type: boolean
  
  schemas:
    
    Angebot:
      description: Ein Veranstaltungsangebot eines Vereins
      type: object
      properties:
        name:
          type: string
          example: JMD
      required:
        - name
    
    Position:
      type: object
      description: Eine Vorstandsposition
      properties:
        name:
          type: string
          example: Vorsitzende/r
        id:
          type: integer
          example: 3
      required:
        - name
        - id
    
    User:
      description: Ein Nutzer des Systems
      type: object
      properties:
        name:
          type: string
          description: Bürgerlicher Name des Nutzers
          example: Max Mustermann
        alias:
          type: string
          example: mmuster
        address:
          type: string
          description: Postalische Adresse des Benutzers
          example: |-
            Großer Platz 1
            12345 Entenhausen
        city:
          type: string
          description: Wohnort des Benutzers
          example: Entenhausen
        mail:
          type: string
          description: Mail-Adresse des Nutzers
          example: max@mustermann.de
        phone:
          type: string
          description: Telefonnummer des Nutzers
          example: 01234 65879
        mobile:
          type: string
          description: Handynummer des Nutzers
          example: 0172 5464657
      required:
        - name
        - alias
        - city
    
    PositionUser:
      description: Ein Vorstandsmitglied
      type: object
      properties:
        user:
          type: integer
          example: 13
          description: Die `id` des Nutzers
        admin:
          type: boolean
          description: Der Nutzer hat Admin-Rechte in dem Verein
          example: true
        address:
          type: string
          description: Die Adresse des Nutzers in seiner Funktion
        mail:
          type: string
          description: Die Mail-Adresse des Nutzers in seiner Funktion
        phone:
          type: string
          description: Die Telefonnummer der Nutzers in seiner Funktion
      required:
        - user
        - admin
    
    ClubPosition:
      description: |
        Eine Vorstandsposition in einem Verein
      type: object
      properties:
        position:
          $ref: "#/components/schemas/Position"
        state:
          type: string
          enum:
            - regular
            - vacant
            - temporary
          description: |
            Der aktuelle Zustand des Vorstandspostens
            
            - `vacant`: Der Posten ist nicht besetzt, `user` ist nicht zu setzen
            - `regular`: Der Posten wurde regulär gewählt, `user` muss angegeben werden
            - `temporary`: Der Posten ist kommisarisch vergeben, `user` muss angegeben werden
        user:
          $ref: "#/components/schemas/PositionUser"
        
      required:
        - position
        - state
    
    Place:
      type: object
      description: Ein Trainingsraum eines Vereins
      properties:
        name:
          type: string
          description: Ein Name für die Location
          example: Clubheim
        address:
          type: string
          description: Die Adresse des Raums
          example: |-
            Sportplatz 2
            12345 Entenhausen
        area:
          type: integer
          description: Die nutzbare Tanz-Fläche an der Trainingsmöglichkeit in qm
          example: 150
      required:
        - name
        - address
    
    Club:
      type: object
      properties:
        id:
          type: integer
          description: ID des Vereins
          example: 3
        name:
          type: string
          description: Der Name des Vereins
          example: TC Entenhausen e.V.
        address:
          type: string
          description: Die Geschäftsadresse des Vereins
          example: |-
            Rathausplatz 12
            12345 Entenhausen
        city:
          type: string
          description: Die Stadt des Vereins
          example: Entenhausen
        homepage:
          type: string
          description: Die URL zur Homepage des Vereins
          example: http://tsc-entenhausen.de
        mail:
          type: string
          description: Die Mail-Adresse des Vereins
          example: info@tsc-entenhausen.de
        iban:
          type: string
          description: Die IBAN Nummer des Vereins
          example: DE12 1234 5678 9012 34
        bic:
          type: string
          description: Die BIC Nummer des Vereins
          example: ABDECDEEH
        president:
          type: string
          description: Der Alias des Vorstandsvorsitzendes des Vereins
          example: dduck
      required:
        - name
        - address
        - city
        - homepage
        - mail
        - president
    
    ConfirmationOfCharitability:
      description: Bescheinigung der Gemeinnützigkeit
      type: object
      properties:
        id:
          type: integer
          example: 44
          description: id der Bescheinigung
        startingDay:
          type: integer
          example: 12
          description: Tag der Ausstellung des Bescheids
        startingMonth:
          type: integer
          example: 3
          description: Monat der Ausstellung des Bescheids
        startingYear:
          type: integer
          example: 2019
          description: Jahr der Ausstellung des Bescheids
        user:
          type: string
          example: mmuster
          description: Der Alias des Nutzers
      required:
        - id
        - startingDay
        - startingMonth
        - startingYear
        - user
    

tags:
  - name: Benutzer
    description: Zugriff auf die Stammdaten der Nutzer des internen Bereichs
  - name: Verein
    description: Zugriff und Anpassen der Einstellungen eines Vereins
  - name: Vorstandsposten
    description: Festlegen der möglichen Vorstandsposten in einem Verein
  - name: Vorstand
    description: Aktuell vergebene Vostandsposten
  - name: Trainingsangebote
    description: Tanz- und Trainingsangebote eines Vereins
  - name: Trainingsräume
    description: Vorhandene Räume in denen Training abgehalten werden kann
  - name: Gemeinnützigkeit
    description: Bescheinigungen zur Gemeinnützigkeit einreichen
  - name: Sonstiges
    description: Zugriff auf statische Konfigurationen

paths:
  
  /offers:
    get:
      tags: [Sonstiges]
      summary: Alle im Verband registrierten Angebote abrufen
      security: []
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Angebot"
              example:
                - name: JMD
                - name: Breitensport
  
  /positions:
    get:
      tags: [Sonstiges]
      summary: Alle möglichen Vorstandspositionen abrufen
      security: []
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Position"
              example:
                - name: Vorsitzende/r
                  id: 2
                - name: Sportwart/in
                  id: 5
  
  /me:
    get:
      tags: [Benutzer]
      summary: Die Eigenschaften des aktuell eingeloggten Benutzers abrufen
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        401:
          $ref: "#/components/responses/notAuth"
    put:
      tags: [Benutzer]
      summary: Die Eigenschaften des aktuellen Benutzers aktualisieren
      requestBody:
        description: Die festzulegenden Eigenschaften, nicht angegebene Eigenschaften werden gelöscht
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: Maximilian Mustermann
                address:
                  type: string
                  example: |-
                    Großer Platz 2
                    12345 Entenhausen
                city:
                  type: string
                  example: Entenhausen
                mail:
                  type: string
                  example: m.mustermann@tld.com
                phone:
                  type: string
                  example: 01234 6575 32145
                mobile:
                  type: string
                  example: 0173 654 8543 69
              required:
                - name
                - address
                - city
                - mail
      responses:
        200:
          $ref: "#/components/responses/ok"
        401:
          $ref: "#/components/responses/notAuth"
        403:
          $ref: "#/components/responses/notAllowed"
  
  /clubs:
    get:
      tags: [Verein]
      summary: Alle Vereine abrufen
      security: []
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Club"
  
  /club/{clubid}:
    parameters:
      - name: clubid
        description: Die `id` des Vereins
        in: path
        required: true
        schema:
          type: integer
          example: 10
    get:
      tags: [Verein]
      summary: Details eines Vereins abrufen
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Club"
    put:
      tags: [Verein]
      summary: Die Daten eines Vereins anpassen
      requestBody:
        description: Die festzulegenden Eigenschaften, nicht angegebene Eigenschaften werden gelöscht
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: TSC Entenhausen e.V
                address:
                  type: string
                  example: |-
                    Großer Platz 1
                    12345 Entenhausen
                city:
                  type: string
                  example: Entenhausen
                homepage:
                  type: string
                  example: https://tsc-entenhausen.de
                mail:
                  type: string
                  example: vorstand@tsc-entenhausen.de
                iban:
                  type: string
                  example: DE12 3456 7890 1234 56
                bic:
                  type: string
                  example: ABCD DEEF GHI
                presidentid:
                  type: integer
                  example: 12
              required:
                - name
                - address
                - city
                - mail
                - iban
                - praesidentid
            example:
              sdf
      responses:
        200:
          $ref: "#/components/responses/ok"
        401:
          $ref: "#/components/responses/notAuth"
        403:
          $ref: "#/components/responses/notAllowed"
        
  /club/{clubid}/position:
    parameters:
      - name: clubid
        in: path
        required: true
        schema:
          type: integer
    
    post:
      tags: [Vorstandsposten]
      summary: Einen neuen Posten im Vorstand schaffen
      description: |
        Dieser Vorgang erzeugt einen neuen Posten im Vorstand.
        Dies ist nur bei einer Anpassung der Vereinsstruktur notwendig.
        
        Zum Bearbeiten der aktuell tätigen Vorstandsposten müssen die Befehle aus der Gruppe Vorstand genutzt werden.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: integer
                  description: Die id des hinzuzufügenden Postens
                  example: 2
      responses:
        200:
          $ref: "#/components/responses/ok"
        401:
          $ref: "#/components/responses/notAuth"
        403:
          $ref: "#/components/responses/notAllowed"
  
  /club/{clubid}/position/{positionid}:
    parameters:
      - name: clubid
        required: true
        in: path
        schema:
          type: integer
      - name: positionid
        required: true
        in: path
        schema:
          type: integer
    
    delete:
      tags: [Vorstandsposten]
      summary: Einen Posten aus dem Vorstand entfernen
      description: |
        Dieser Vorgang entfernt einen Posten aus dem Vorstand.
        Dies ist nur bei einer Anpassung der Vereinsstruktur notwendig.
        
        Zum Bearbeiten der aktuell tätigen Vorstandsposten müssen die Befehle aus der Gruppe Vorstand genutzt werden.
      responses:
        200:
          $ref: "#/components/responses/ok"
        401:
          $ref: "#/components/responses/notAuth"
        404:
          description: Posten ist aktuell nicht vorhanden
        403:
          $ref: "#/components/responses/notAllowed"
    
  /club/{clubid}/persons:
    parameters:
      - name: clubid
        required: true
        in: path
        schema:
          type: integer
    get:
      tags: [Verein, Vorstand]
      summary: Alle Vorstandsposten ermitteln
      security: []
      responses:
        200:
          description: ok
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ClubPosition"
  
  /club/{clubid}/person/{positionid}:
    parameters:
      - name: clubid
        in: path
        required: true
        schema:
          type: integer
      - name: positionid
        in: path
        required: true
        schema:
          type: integer
    get:
      tags: [Vorstand]
      summary: Einen bestimmten Vorstandsposten ermitteln
      security: []
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    example: 3
                  mapping:
                    $ref: "#/components/schemas/ClubPosition"
    delete:
      tags: [Vorstand]
      summary: Einen Vorstandsposten als vakant markieren
      responses:
        200:
          $ref: "#/components/responses/ok"
        401:
          $ref: "#/components/responses/notAuth"
        403:
          $ref: "#/components/responses/notAllowed"
        400:
          $ref: "#/components/responses/error"
    put:
      tags: [Vorstand]
      summary: Einen Vorstandsposten neu besetzen oder die Einstellungen anpassen
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                state:
                  type: string
                  enum:
                    - regular
                    - temporary
                user:
                  $ref: "#/components/schemas/PositionUser"
              required:
                - state
                - user
      responses:
        200:
          $ref: "#/components/responses/ok"
        401:
          $ref: "#/components/responses/notAuth"
        403:
          $ref: "#/components/responses/notAllowed"
        400:
          $ref: "#/components/responses/error"

  /club/{clubid}/offers:
    parameters:
      - name: clubid
        required: true
        in: path
        schema:
          type: integer
    get:
      tags: [Trainingsangebote]
      summary: Alle Angebote des Vereins abfragen
      security: []
      responses:
        200:
          description: ok
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      example: JMD
        404:
          description: Der angegebene Verein konnte nciht gefunden werden
    put:
      tags: [Trainingsangebote]
      summary: Die Angebote des Vereins festlegen
      requestBody:
        required: true
        description: Alle angebotenen Trainingsangebote, nicht aufgeführte werden gelöscht
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
      responses:
        200:
          $ref: "#/components/responses/ok"
        401:
          $ref: "#/components/responses/notAuth"
        403:
          $ref: "#/components/responses/notAllowed"
        400:
          $ref: "#/components/responses/error"
  
  /club/{clubid}/places:
    parameters:
      - name: clubid
        in: path
        required: true
        schema:
          type: integer
    
    get:
      tags: [Trainingsräume]
      summary: Die Trainingsräumlichkeiten des Vereins ermitteln
      security: []
      responses:
        200:
          description: ok
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  title: Raum
                  properties:
                    id:
                      type: integer
                      description: id des Raumes
                      example: 15
                    place:
                      $ref: "#/components/schemas/Place"
        404:
          description: Der Verein konnte nicht gefunden werden.
  
  /club/{clubid}/place:
    parameters:
      - name: clubid
        required: true
        in: path
        schema:
          type: integer
    post:
      tags: [Trainingsräume]
      summary: Einen neuen Raum hinzufügen
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Place"
      responses:
        200:
          description: ok, Rückgabewert ist die `id` des neuen Raums
          content:
            application/json:
              schema:
                type: integer
                example: 9
        401:
          $ref: "#/components/responses/notAuth"
        403:
          $ref: "#/components/responses/notAllowed"
  
  /club/{clubid}/place/{placeid}:
    parameters:
      - name: clubid
        required: true
        in: path
        schema:
          type: integer
      - name: placeid
        required: true
        in: path
        schema:
          type: integer
    
    delete:
      tags: [Trainingsräume]
      summary: Einen bestehenden Raum entfernen
      responses:
        200:
          $ref: "#/components/responses/ok"
        401:
          $ref: "#/components/responses/notAuth"
        403:
          $ref: "#/components/responses/notAllowed"
        400:
          $ref: "#/components/responses/error"
    put:
      tags: [Trainingsräume]
      summary: Einen bestehenden Raum anpassen
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Place"
      responses:
        200:
          $ref: "#/components/responses/ok"
        401:
          $ref: "#/components/responses/notAuth"
        403:
          $ref: "#/components/responses/notAllowed"
        400:
          $ref: "#/components/responses/error"
  
  /club/{clubid}/charity:
    parameters:
      - name: clubid
        required: true
        in: path
        schema:
          type: integer
    
    get:
      summary: Den aktuellen Bescheid der Gemeinnützigkeit abfragen
      tags: [Gemeinnützigkeit]
      deprecated: true
      responses:
        200:
          description: ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConfirmationOfCharitability"
        401:
          $ref: "#/components/responses/notAuth"
        404:
          description: Verein wurde nicht gefunden
        400:
          $ref: "#/components/responses/error"
  
  /club/{clubid}/charities:
    parameters:
      - name: clubid
        required: true
        in: path
        schema:
          type: integer
    
    get:
      summary: Den hochgeladenen Bescheide abfragen
      tags: [Gemeinnützigkeit]
      deprecated: true
      responses:
        200:
          description: ok
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    entry:
                      $ref: "#/components/schemas/ConfirmationOfCharitability"
                    state:
                      type: string
                      enum:
                        - active
                        - renewed
                        - rejected
                        - pending
                  required:
                    - entry
                    - state
        401:
          $ref: "#/components/responses/notAuth"
        404:
          description: Verein wurde nicht gefunden
        403:
          $ref: "#/components/responses/notAllowed"
        400:
          $ref: "#/components/responses/error"
    post:
      summary: Einen neuen Bescheid hochladen
      tags: [Gemeinnützigkeit]
      deprecated: true
      requestBody:
        description: Die relevanten Daten
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                config:
                  type: object
                  description: Meta-Daten der übermittelten Datei
                  properties:
                    startingDay:
                      type: integer
                      example: 22
                      description: Tag der Ausstellung des Bescheids
                    startingMonth:
                      type: integer
                      example: 11
                      description: Monat der Ausstellung des Bescheids
                    startingYear:
                      type: integer
                      example: 2020
                      description: Jahr der Ausstellung des Bescheids
                  required:
                    - startingDay
                    - startingMonth
                    - startingYear
                file:
                  type: string
                  description: Die Datei (PDF/PNG/JPG) des gescannten Bescheids
                  format: binary
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    example: 45
                    description: Die `id` des neu eingetragenen Bescheids
                required:
                  - id
        401:
          $ref: "#/components/responses/notAuth"
        403:
          $ref: "#/components/responses/notAllowed"
        400:
          $ref: "#/components/responses/error"
      
  /club/{clubid}/charity/{charityid}:
    parameters:
      - name: clubid
        required: true
        in: path
        schema:
          type: integer
      - name: charityid
        required: true
        in: path
        schema:
          type: integer
    
    get:
      summary: Einen bestimmten Bescheid der Gemeinnützigkeit abfragen
      tags: [Gemeinnützigkeit]
      deprecated: true
      responses:
        200:
          description: ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConfirmationOfCharitability"
        401:
          $ref: "#/components/responses/notAuth"
        400:
          $ref: "#/components/responses/error"
    put:
      summary: Den Status eines Bescheids aktualisieren
      tags: [Gemeinnützigkeit]
      deprecated: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startingDay:
                  type: integer
                  example: 11
                  description: Der Ausstellungstag des Bescheids
                startingMonth:
                  type: integer
                  example: 5
                  description: Der Ausstellungsmonat des Bescheids
                startingYear:
                  type: integer
                  example: 2019
                  description: Das Ausstellungsjahr des Bescheids
                state:
                  type: string
                  description: Der (neue) Zustand des Bescheids
                  enum:
                    - active
                    - rejected
                    - pending
      responses:
        200:
          $ref: "#/components/responses/ok"
        401:
          $ref: "#/components/responses/notAuth"
        403:
          $ref: "#/components/responses/notAllowed"
        400:
          $ref: "#/components/responses/error"
    delete:
      summary: Einen abgelehnten oder zu prüfenden Bescheid löschen
      tags: [Gemeinnützigkeit]
      deprecated: true
      responses:
        200:
          $ref: "#/components/responses/ok"
        401:
          $ref: "#/components/responses/notAuth"
        403:
          $ref: "#/components/responses/notAllowed"
        400:
          $ref: "#/components/responses/error"
    
  /club/{clubid}/charity/{charityid}/pdf:
    parameters:
      - name: clubid
        required: true
        in: path
        schema:
          type: integer
      - name: charityid
        required: true
        in: path
        schema:
          type: integer
    
    get:
      summary: Den Scan eines Bescheids abfragen
      tags: [Gemeinnützigkeit]
      deprecated: true
      responses:
        200:
          description: ok
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        401:
          $ref: "#/components/responses/notAuth"
        400:
          $ref: "#/components/responses/error"
  
  /me/mails:
    get:
      tags: [Benutzer]
      summary: Die Mails des Nutzers abfragen
      responses:
        200:
          description: ok
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    mail:
                      type: string
                      example: d.duck@entenhausen.de
        401:
          $ref: "#/components/responses/notAuth"
  
  /me/mail:
    post:
      tags: [Benutzer]
      summary: Eine neue Mail-Adresse des Nutzers registrieren
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                mail:
                  type: string
                  example: dagobert@tsc-entenhausen.de
                  description: Die neu hinzuzufügende Mail-Adresse
              required: [mail]
      responses:
        200:
          description: ok
        401:
          $ref: "#/components/responses/notAuth"
        400:
          $ref: "#/components/responses/error"
    delete:
      tags: [Benutzer]
      summary: Eine neue Mail-Adresse des Nutzers registrieren
      parameters:
        - name: mail
          in: query
          required: true
          schema:
            type: string
            example: dagobert@tsc-entenhausen.de
            description: Die neu hinzuzufügende Mail-Adresse
      responses:
        200:
          $ref: "#/components/responses/ok"
        401:
          $ref: "#/components/responses/notAuth"
        400:
          $ref: "#/components/responses/error"
  
  /confirm_mail/{alias}/{token}:
    get:
      tags: [Benutzer]
      summary: Eine Mail eines Benutzers bestätigen
      parameters:
        - name: alias
          in: path
          required: true
          schema:
            type: integer
            example: 12
            description: Die ID des Benutzers, der die Mail hinzugefügt werden soll
        - name: token
          in: path
          required: true
          schema:
            type: string
            example: "asdfkhjg7854-hjkhjf-234"
            description: Der Token, der per Mail verschickt wurde, um die Mail zu bestätigen.
      responses:
        200:
          $ref: "#/components/responses/ok"
      security: []
  
  /me/resend-token:
    post:
      tags: [Benutzer]
      summary: Die Mail mit dem Token zur Bestätigung erneut an die Mailadresse schicken
      parameters:
        - name: mail
          in: query
          required: true
          schema:
            type: string
            example: "foo@example.com"
            description: Die Mail, die bestätigt werden soll.
      responses:
        200:
          $ref: "#/components/responses/ok"
        401:
          $ref: "#/components/responses/notAuth"
        400:
          $ref: "#/components/responses/error"
  
  /change-password:
    post:
      tags: [Benutzer]
      summary: Das Passwort eines Nutzers anpassen
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user:
                  type: integer
                  example: 12
                  description: Die `id` des Nutzers, dessen Passwort angepasst werden soll. Wenn nicht gegeben wird das Passwort des eingeloggten Nutzers geändert
                new_pasword:
                  type: string
                  example: very_save_password
                  description: Das neue Passwort des Nutzers
      responses:
        200:
          $ref: "#/components/responses/ok"
        401:
          $ref: "#/components/responses/notAuth"
        400:
          $ref: "#/components/responses/error"
  
  /reset-password:
    get:
      tags: [Benutzer]
      summary: Das Passwort eines Nutzers zurücksetzen
      parameters:
        - name: mail
          required: true
          in: query
          schema:
            type: string
            description: Die Mail des Nutzers, dessen Passwort zurück gesetzt werden soll
            example: "foo@example.com"
      responses:
        200:
          $ref: "#/components/responses/ok"
        400:
          $ref: "#/components/responses/error"
      security: []
  
  /users/search:
    get:
      tags: [Benutzer]
      summary: Nach einem Nutzer suchen
      parameters:
        - name: name
          in: query
          schema:
            type: string
        - name: city
          in: query
          schema:
            type: string
        - name: mail
          in: query
          schema:
            type: string
        - name: phone
          in: query
          schema:
            type: string
      responses:
        200:
          description: ok
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      example: 23
                      description: Die `id` des Nutzers
                    name:
                      type: string
                      example: Dagobert Duck
                      description: Der Name des Nutzers
                    city:
                      type: string
                      example: Entenhausen
                  required:
                    - id
                    - name
                    - city
        401:
          $ref: "#/components/responses/notAuth"
        400:
          $ref: "#/components/responses/error"
  
  /user:
    post:
      tags: [Benutzer]
      summary: Einen neuen Benutzer anlegen
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: Daisy Duck
                mail:
                  type: string
                  example: daisy@ducks.org
              required: [name, mail]
      responses:
        200:
          $ref: "#/components/responses/ok"
        401:
          $ref: "#/components/responses/notAuth"
        400:
          $ref: "#/components/responses/error"
  
  /user/{useralias}:
    parameters:
      - name: useralias
        in: path
        required: true
        schema:
          type: string
          example: dduck
    
    get:
      tags: [Benutzer]
      summary: Die Eigenschaften eines Nutzers erfragen
      security: []
      responses:
        200:
          description: ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
  
security:
  - jwt: []