{"openapi":"3.0.1","info":{"title":"Football Confederation API","description":"REST API for the Football Confederation Club & Player Registry.\n\n**Authentication flow:**\n1. Register via `POST /club`\n2. Obtain a JWT token via `POST /login`\n3. Click **Authorize** and enter `Bearer <your-token>`\n4. Use the token in the `Authorization` header for all other requests\n","contact":{"name":"Football Confederation","email":"api@confederation.football"},"version":"1.0.0"},"servers":[{"url":"http://98.87.156.14:8080","description":"Generated server url"}],"tags":[{"name":"Clubs","description":"Club registration and management"},{"name":"Players","description":"Manage federated players within a club"},{"name":"Authentication","description":"Obtain a JWT token to access the API"}],"paths":{"/club/{clubId}":{"get":{"tags":["Clubs"],"summary":"Get details of a specific club","description":"Public clubs: visible to all authenticated users. Private clubs: only accessible by the owning club.","operationId":"getClubDetail","parameters":[{"name":"clubId","in":"path","description":"UUID of the club","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"403":{"description":"Access denied (private club)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"200":{"description":"Club details including player count","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ClubDetailResponse"}}}},"404":{"description":"Club not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"bearerAuth":[]}]},"put":{"tags":["Clubs"],"summary":"Update a club's details","description":"Only the authenticated club can update its own details.","operationId":"updateClub","parameters":[{"name":"clubId","in":"path","description":"UUID of the club to update","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClubUpdateRequest"}}},"required":true},"responses":{"404":{"description":"Club not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"200":{"description":"Club updated successfully","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ClubDetailResponse"}}}},"400":{"description":"Validation error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Not the owner of this club","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"bearerAuth":[]}]}},"/club/{clubId}/player/{playerId}":{"get":{"tags":["Players"],"summary":"Get full details of a player","description":"For private clubs only the owning club may access player details.","operationId":"getPlayerDetail","parameters":[{"name":"clubId","in":"path","description":"UUID of the club","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"playerId","in":"path","description":"UUID of the player","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"403":{"description":"Access denied","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Player or club not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"200":{"description":"Player details","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PlayerDetailResponse"}}}}},"security":[{"bearerAuth":[]}]},"put":{"tags":["Players"],"summary":"Update a player's details","description":"Only the owning club can update its players.","operationId":"updatePlayer","parameters":[{"name":"clubId","in":"path","description":"UUID of the club","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"playerId","in":"path","description":"UUID of the player","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlayerRequest"}}},"required":true},"responses":{"409":{"description":"Player email already in use","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Player or club not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"400":{"description":"Validation error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"200":{"description":"Player updated","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PlayerDetailResponse"}}}},"403":{"description":"Not the owner of this club","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"bearerAuth":[]}]},"delete":{"tags":["Players"],"summary":"Delete a player from a club","description":"Only the owning club can delete its players.","operationId":"deletePlayer","parameters":[{"name":"clubId","in":"path","description":"UUID of the club","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"playerId","in":"path","description":"UUID of the player","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Player deleted successfully"},"404":{"description":"Player or club not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Not the owner of this club","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"bearerAuth":[]}]}},"/login":{"post":{"tags":["Authentication"],"summary":"Log in and receive a JWT token","operationId":"login","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginRequest"}}},"required":true},"responses":{"401":{"description":"Invalid credentials","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"400":{"description":"Validation error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"200":{"description":"Login successful","content":{"*/*":{"schema":{"$ref":"#/components/schemas/LoginResponse"}}}}}}},"/club":{"get":{"tags":["Clubs"],"summary":"List all public Football Clubs","description":"Returns clubs with public=true. Optionally filter by name (partial, case-insensitive) and/or federation (exact, case-insensitive).","operationId":"listPublicClubs","parameters":[{"name":"name","in":"query","description":"Filter by name (partial match on officialName or popularName)","required":false,"schema":{"type":"string"}},{"name":"federation","in":"query","description":"Filter by federation acronym (exact match, e.g. UEFA)","required":false,"schema":{"type":"string"}}],"responses":{"401":{"description":"Missing or invalid token","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"200":{"description":"List of public clubs","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ClubSummaryResponse"}}}}}},"security":[{"bearerAuth":[]}]},"post":{"tags":["Clubs"],"summary":"Register a new Football Club","operationId":"register","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClubRegistrationRequest"}}},"required":true},"responses":{"201":{"description":"Club registered successfully","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ClubDetailResponse"}}}},"409":{"description":"Username already in use","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"400":{"description":"Validation error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/club/{clubId}/player":{"get":{"tags":["Players"],"summary":"List players of a club","description":"Returns id, givenName and familyName only. Optionally filter by name (partial) and/or nationality (exact). For private clubs only the owning club may access this list.","operationId":"listPlayers","parameters":[{"name":"clubId","in":"path","description":"UUID of the club","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"name","in":"query","description":"Filter by name (partial match on givenName or familyName)","required":false,"schema":{"type":"string"}},{"name":"nationality","in":"query","description":"Filter by nationality (exact match, case-insensitive)","required":false,"schema":{"type":"string"}}],"responses":{"403":{"description":"Access denied","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Club not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"200":{"description":"Player list","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PlayerSummaryResponse"}}}}}},"security":[{"bearerAuth":[]}]},"post":{"tags":["Players"],"summary":"Register a new player under a club","description":"Only the owning club can add players.","operationId":"createPlayer","parameters":[{"name":"clubId","in":"path","description":"UUID of the club","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlayerRequest"}}},"required":true},"responses":{"409":{"description":"Player email already in use","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Club not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"400":{"description":"Validation error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"201":{"description":"Player created","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PlayerDetailResponse"}}}},"403":{"description":"Not the owner of this club","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"bearerAuth":[]}]}}},"components":{"schemas":{"ClubUpdateRequest":{"required":["federation","officialName","popularName"],"type":"object","properties":{"officialName":{"type":"string","description":"Official registered name of the club","example":"FC Barcelona S.A.D."},"popularName":{"type":"string","description":"Commonly-known name of the club","example":"Barça"},"federation":{"maxLength":8,"minLength":0,"type":"string","description":"Federation acronym (max 8 chars)","example":"RFEF"},"publicVisible":{"type":"boolean","description":"Whether club details are publicly visible to other users","example":false}},"description":"Payload to update an existing Football Club"},"ErrorResponse":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code","format":"int32","example":400},"error":{"type":"string","description":"Short error code","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable description of the error","example":"username must be a valid email address"}},"description":"Error response body"},"ClubDetailResponse":{"type":"object","properties":{"id":{"type":"string","description":"Internal club identifier (UUID)","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"},"officialName":{"type":"string","description":"Official registered name","example":"FC Barcelona"},"popularName":{"type":"string","description":"Commonly-known name","example":"Barça"},"federation":{"type":"string","description":"Federation acronym","example":"RFEF"},"publicVisible":{"type":"boolean","description":"Whether the club is publicly visible","example":true},"playerCount":{"type":"integer","description":"Number of federated players registered in this club","format":"int32","example":25}},"description":"Full details of a Football Club"},"PlayerRequest":{"required":["dateOfBirth","email","familyName","givenName","nationality"],"type":"object","properties":{"givenName":{"type":"string","description":"Player's given (first) name","example":"Lionel"},"familyName":{"type":"string","description":"Player's family (last) name","example":"Messi"},"nationality":{"type":"string","description":"Player's nationality","example":"Argentine"},"email":{"type":"string","description":"Player's email (must be unique in the system)","example":"l.messi@club.com"},"dateOfBirth":{"type":"string","description":"Player's date of birth (ISO-8601: YYYY-MM-DD)","format":"date","example":"1987-06-24"}},"description":"Payload to register a new Player under a Club"},"PlayerDetailResponse":{"type":"object","properties":{"id":{"type":"string","description":"Internal player identifier (UUID)","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"},"givenName":{"type":"string","description":"Player's given name","example":"Lionel"},"familyName":{"type":"string","description":"Player's family name","example":"Messi"},"nationality":{"type":"string","description":"Player's nationality","example":"Argentine"},"email":{"type":"string","description":"Player's email","example":"l.messi@club.com"},"dateOfBirth":{"type":"string","description":"Player's date of birth (YYYY-MM-DD)","format":"date","example":"1987-06-24"},"clubId":{"type":"string","description":"ID of the club this player belongs to (UUID)","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"}},"description":"Full details of a Player"},"LoginRequest":{"required":["password","username"],"type":"object","properties":{"username":{"type":"string","description":"Club email used at registration","example":"info@townfc.com"},"password":{"type":"string","description":"Club password","example":"iTk19!n."}},"description":"Login credentials"},"LoginResponse":{"type":"object","properties":{"token":{"type":"string","description":"Bearer JWT token to be sent in the Authorization header","example":"eyJhbGciOiJIUzI1NiJ9..."}},"description":"JWT token issued after a successful login"},"ClubRegistrationRequest":{"required":["federation","officialName","password","popularName","publicVisible","username"],"type":"object","properties":{"username":{"type":"string","description":"Club login email (must be unique)","example":"info@townfc.com"},"password":{"maxLength":2147483647,"minLength":8,"type":"string","description":"Password (min 8 chars)","example":"iTk19!n."},"officialName":{"type":"string","description":"Official registered name of the club","example":"FC Barcelona"},"popularName":{"type":"string","description":"Commonly-known name of the club","example":"Barça"},"federation":{"maxLength":8,"minLength":0,"type":"string","description":"Federation acronym the club belongs to (max 8 chars)","example":"RFEF"},"publicVisible":{"type":"boolean","description":"Whether club details are publicly visible to other users","example":true}},"description":"Payload to register a new Football Club"},"ClubSummaryResponse":{"type":"object","properties":{"id":{"type":"string","description":"Internal club identifier (UUID)","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"},"officialName":{"type":"string","description":"Official registered name","example":"FC Barcelona"},"popularName":{"type":"string","description":"Commonly-known name","example":"Barça"},"federation":{"type":"string","description":"Federation acronym","example":"RFEF"}},"description":"Summary of a public Football Club (list view)"},"PlayerSummaryResponse":{"type":"object","properties":{"id":{"type":"string","description":"Internal player identifier (UUID)","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"},"givenName":{"type":"string","description":"Player's given name","example":"Lionel"},"familyName":{"type":"string","description":"Player's family name","example":"Messi"}},"description":"Player summary (list view)"}},"securitySchemes":{"bearerAuth":{"type":"http","description":"Enter the JWT token obtained from POST /login","scheme":"bearer","bearerFormat":"JWT"}}}}