PHP-Course/exam/api/docs/api.yaml

openapi: 3.0.0
info:
  title: PHP Course Exam
  version: 1.0.0
  contact:
    name: Kilian Kurt Hofmann
    email: khofmann@zedat.fu-berlin.de
  description: PHP Course (ABV FU Berlin) 2024 Exam
paths:
  /login:
    post:
      summary: Login
      description: Log in user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LoginRequest"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BooleanResponse"
              examples:
                Success:
                  value: true
        400:
          description: Missing fields
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                Missing fields:
                  value: { "message": "Missing email" }
        401:
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                Invalid username or password:
                  value: { "message": "Invalid username or password" }
        404:
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                User not found:
                  value: { "message": "User not found" }
        500:
          description: Failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                Failed:
                  value: { "message": "Login failed" }
      tags:
        - Login/Logout
  /logout:
    post:
      summary: Logout
      description: Log out user
      security:
        - BasicAuth: []
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BooleanResponse"
              examples:
                Success:
                  value: true
      tags:
        - Login/Logout
  /register:
    post:
      summary: Register
      description: Register a new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RegisterRequest"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BooleanResponse"
              examples:
                Success:
                  value: true
        400:
          description: Missing fields or duplicate
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                Missing fields:
                  value: { "message": "Missing email" }
                Duplicate:
                  value:
                    {
                      "message": "A user with this username or email already exists",
                    }
      tags:
        - Register
  /user{id}:
    get:
      summary: Get user
      description: Get user by ID
      security:
        - BasicAuth: []
      parameters:
        - name: id
          in: path
          description: User ID
          required: true
          schema:
            type: integer
            format: int14
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserResponse"
              examples:
                Success:
                  value:
                    {
                      "id": 1,
                      "username": "Admin",
                      "status": 1,
                      "email": "marvin@zedat.fu-berlin.de",
                      "image": "profilbilder\\/admin.svg",
                      "isAdmin": true,
                    }
        404:
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                User not found:
                  value: { "message": "User not found" }
      tags:
        - User
    patch:
      summary: Update user
      description:
        Update user with ID. Fields are updated in order username, password, image. If one fails, subsequent are not updated. <br>
        Use special ID <code>self</code> to update logged in user. <br>
        Requires logged in user to have admin permissions for any ID other than <code>self</code>.
      security:
        - BasicAuth: []
      parameters:
        - name: id
          in: path
          description: User ID
          required: true
          schema:
            type: integer
            format: int14
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserUpdateRequest"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BooleanResponse"
              examples:
                Success:
                  value: true
        404:
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                User not found:
                  value: { "message": "User not found" }
        500:
          description: Update failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                User not found:
                  value: { "message": "Failed to update username" }
      tags:
        - User
    delete:
      summary: Delete user
      description: Delete user with ID. <br>
        Requires logged in user to have admin permissions.
      security:
        - BasicAuth: []
      parameters:
        - name: id
          in: path
          description: User ID
          required: true
          schema:
            type: integer
            format: int14
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BooleanResponse"
              examples:
                Success:
                  value: true
        404:
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                User not found:
                  value: { "message": "User not found" }
      tags:
        - User

externalDocs:
  url: https://khofmann.userpage.fu-berlin.de/phpCourse/exam/api/docs/
security: []
servers:
  - url: https://khofmann.userpage.fu-berlin.de/phpCourse/exam/api/
components:
  schemas:
    BooleanResponse:
      type: boolean
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
    LoginRequest:
      type: object
      required:
        - username
        - password
      properties:
        username:
          type: string
        password:
          type: string
    UserResponse:
      type: object
      properties:
        id:
          type: number
        username:
          type: string
        status:
          type: number
        email:
          type: string
        image:
          type: string
          nullable: true
        isAdmin:
          type: boolean
    UserUpdateRequest:
      type: object
      properties:
        username:
          type: string
        password:
          type: string
        image:
          type: string
          format: binary
    RegisterRequest:
      type: object
      required:
        - username
        - email
        - password
      properties:
        username:
          type: string
        email:
          type: string
        password:
          type: string
  securitySchemes:
    BasicAuth:
      type: apiKey
      name: token
      in: header
tags:
  - name: Login/Logout
  - name: Register
  - name: User