add api description

[raphael-frank]

I added descriptions to all API endpoints. They consist of a short summary followed by a list of what this endpoint returns based on the permission/role of the caller.
Note that these permissions are additive so for example if you are a member of a team and a director of a different sport you get some permissions from that sport and the different team in the same response. The web client will be responsible for filtering out the information it truly needs or it could just call the detail endpoints that only return one object per request.

Closes #7.

[raphael-frank]

@FadyGergesRezk @f-s-h In the future, we might change the letter service and report service endpoints so that one can limit the scope so for example only send mail to team and for report only generate report in context of a certain team. For now, this is not too relevant.

[FadyGergesRezk]

I have 3 points regarding this that need some clarification:

1. Should member creation set a Keycloak credential directly, or go through Keycloak's admin API?
2. for get all members i think relying on the client to filter wont really work as a privacy thing since the full response is still visible in devtools no matter what the ui shows. so any trainee could just read every member's data... shouldnt the filtering be server side here like getMemberDetails already does?
3. theres members/{member_id} but the client doesnt have its own member id, only the email from the token... could we either get the member id as a claim in the token or let me resolve myself by email so i dont have to pull the whole list just to find my own id

[FadyGergesRezk]

quick follow up on 3 — since the team/feedback/transaction reference fields are all member UUIDs in the db (not emails), resolving by email still leaves me needing my own UUID to match against them, so the token claim is probably the real fix

[raphael-frank]

Regarding the points:

1. Member creation should create the keycloak client directly and for this a password will be parsed. Since we dont want unauthorized creation of new users, only admins can create new users.
2. Its by design that everyone can see the member summary of every member (so first/last name and mail address), but details only for members they are supposed to. I think privacy-wise its okay, imagine github (everybody can see those three fields). For example, you might want to display the name of the director of a sport or the trainers of a team you might want to join and for that you have to resolve the member id to its name.
3. Yes I think we definitely want to have ones own client id in the token and not just the mail.

[raphael-frank]

follow up on 3: it is currently possible to receive the own member id as a token claim. Since we set the member id to be the uuid of the keycloak user on creation, you can just use the following code:
const memberId = keycloak.tokenParsed?.sub where the sub claim is the keycloak user uuid.