com_clubs/api/openapi.yaml

1239 lines
33 KiB
YAML

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"
/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"
/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: []