Added first approach of a API definition

This commit is contained in:
Christian Wolf 2020-05-11 10:19:41 +02:00
parent 5e82187518
commit 6eee6a4fe6
2 changed files with 784 additions and 0 deletions

View 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
View 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: []