From 6eee6a4fe64b02f2bfa2eb2eb74c88861921f34c Mon Sep 17 00:00:00 2001 From: Christian Wolf Date: Mon, 11 May 2020 10:19:41 +0200 Subject: [PATCH] Added first approach of a API definition --- api/api Fragen zum Design.md | 4 + api/openapi.yaml | 780 +++++++++++++++++++++++++++++++++++ 2 files changed, 784 insertions(+) create mode 100644 api/api Fragen zum Design.md create mode 100644 api/openapi.yaml diff --git a/api/api Fragen zum Design.md b/api/api Fragen zum Design.md new file mode 100644 index 0000000..4528df8 --- /dev/null +++ b/api/api Fragen zum Design.md @@ -0,0 +1,4 @@ + +# Offene Fragen zum Design + +- Sollen mehrere gleiche Vorstaende auf einer Position zulaessig sein (mehrere stellv. Jugenwarte)? diff --git a/api/openapi.yaml b/api/openapi.yaml new file mode 100644 index 0000000..5b1b606 --- /dev/null +++ b/api/openapi.yaml @@ -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: []