Added first approach of a API definition
This commit is contained in:
parent
5e82187518
commit
6eee6a4fe6
4
api/api Fragen zum Design.md
Normal file
4
api/api Fragen zum Design.md
Normal file
@ -0,0 +1,4 @@
|
||||
|
||||
# Offene Fragen zum Design
|
||||
|
||||
- Sollen mehrere gleiche Vorstaende auf einer Position zulaessig sein (mehrere stellv. Jugenwarte)?
|
||||
780
api/openapi.yaml
Normal file
780
api/openapi.yaml
Normal file
@ -0,0 +1,780 @@
|
||||
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:
|
||||
$ref: "#/components/schemas/User"
|
||||
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:
|
||||
allOf:
|
||||
- $ref: "#/components/schemas/User"
|
||||
title: User
|
||||
description: Der Vorstandsvorsitzende des Vereins
|
||||
required:
|
||||
- name
|
||||
- address
|
||||
- city
|
||||
- homepage
|
||||
- mail
|
||||
- president
|
||||
|
||||
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
|
||||
- name: Trainingsräume
|
||||
- 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"
|
||||
|
||||
|
||||
|
||||
security:
|
||||
- jwt: []
|
||||
Loading…
Reference in New Issue
Block a user