API description using OpenAPI 3.0

openapi: "3.0.0"
info:
  title: "k4ever API"
  version: 1.0.0
  license:
    name: "AGPL+"
servers:
  - url: "http://k4ever.freitagsrunde/api/v1"
paths:
  /users/:
    get:
      summary: "Returns a list of all users"
      operationId: listUsers
      tags:
        - Users
      parameters:
        - name: limit
          in: query
          description: "How many items to return at one time (max 100)"
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: "A paged array of users"
          headers:
            x-next:
              description: "A link to the next page of responses"
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Users"
        default:
          description: "unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    post:
      summary: "Creates a user"
      operationId: createUsers
      tags:
        - Users
      responses:
        '201':
          description: "The user that was created"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        default:
          description: "unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /user/{userId}:
    get:
      summary: "Returns a user"
      operationId: showUserById
      tags:
        - Users
      parameters:
        - name: userId
          in: path
          required: true
          description: "The id of the user to retrieve"
          schema:
            type: string
      responses:
        '200':
          description: "Expected response to a valid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        '404':
          description: "The user could not be found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    put:
      summary: "Updates (if it exists) or creates a user (if it doesnt exist yet)"
      operationId: updateUser
      tags:
        - Users
      parameters:
        - name: userId
          in: path
          required: true
          description: "The id of the user to update"
          schema:
            type: string
      responses:
        '201':
          description: "The user that was updated or created"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        default:
          description: "unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
                
  /user/{userId}/image/:
    get:
      summary: "Returns the profile image of the specified user"
      operationId: showUserProfileImage
      tags:
        - Users
      parameters:
        - name: userId
          in: path
          required: true
          description: "The id of the user to retrieve the profile image for"
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: "The profile image of the user"
          content:
            image/*:
              schema: 
                type: string
                format: binary
        '404':
          description: "The user could not be found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
                
  /user/{userId}/balance_history/:
    get:
      summary: "Returns a list of balance history items for the specified user"
      operationId: showBalanceHistoryByUserId
      tags:
        - Account
      parameters:
        - name: userId
          in: path
          required: true
          description: "The id of the user to retrieve history items for"
          schema:
            type: string
        - name: limit
          in: query
          description: "How many items to return at one time (max 100)"
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: "A paged array of balance history items"
          headers:
            x-next:
              description: "A link to the next page of responses"
              schema:
                type: string
          content:
            application/json:    
              schema:
                $ref: "#/components/schemas/BalanceHistoryItems"
        default:
          description: "unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
                
  /user/{userId}/purchase_history/:
    get:
      summary: "Returns a list of purchase history items for the specified user"
      operationId: showPurchaseHistoryByUserId
      tags:
        - Account
      parameters:
        - name: userId
          in: path
          required: true
          description: "The id of the user to retrieve history items for"
          schema:
            type: string
        - name: limit
          in: query
          description: "How many items to return at one time (max 100)"
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: "A paged array of purchase history items"
          headers:
            x-next:
              description: "A link to the next page of responses"
              schema:
                type: string
          content:
            application/json:    
              schema:
                $ref: "#/components/schemas/PurchaseHistoryItems"
        default:
          description: "unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
                
  /products/:
    get:
      summary: "Returns a list of all products"
      operationId: listProducts
      tags:
        - Products
      parameters:
        - name: limit
          in: query
          description: "How many items to return at one time (max 100)"
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: "A paged array of products"
          headers:
            x-next:
              description: "A link to the next page of responses"
              schema:
                type: string
          content:
            application/json:    
              schema:
                $ref: '#/components/schemas/Products'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
                
    post:
      summary: "Creates a product"
      operationId: createProduct
      tags:
        - Products
      responses:
        '201':
          description: "The product that was created"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Product"
        default:
          description: "unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
                
  /product/{productId}:
    get:
      summary: "Returns a specific product"
      operationId: showProductById
      tags:
        - Products
      parameters:
        - name: productId
          in: path
          required: true
          description: "The id of the product to retrieve"
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: "Expected response to a valid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Product"
        '404':
          description: "The product could not be found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    put:
      summary: "Updates (if it exists) or creates a product (if it doesnt exist yet)"
      operationId: updateProduct
      tags:
        - Products
      parameters:
        - name: productId
          in: path
          required: true
          description: "The id of the product to update"
          schema:
            type: string
      responses:
        '201':
          description: "The product that was updated or created"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Product"
        default:
          description: "unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
                
  /product/{productId}/image/:
    get:
      summary: "Returns the preview image of the specified product"
      operationId: showProductPreviewImage
      tags:
        - Products
      parameters:
        - name: productId
          in: path
          required: true
          description: "The id of the product to retrieve preview item"
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: "The profile image of the product"
          content:
            image/*:
              schema: 
                type: string
                format: binary
        '404':
          description: "The product could not be found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
components:
  schemas:
    User:
      required:
        - id
        - user_name
        - display_name
      properties:
        id:
          description: "A unique identifier for this user"
          type: integer
          format: int64
        user_name:
          description: "A unique username of this user"
          type: string
        display_name:
          description: "The name of this user displayed for other users"
          type: string
        balance:
          description: "The current balance of this user"
          type: number
          format: double
        permissions:
          description: "A list of this user's permissions"
          type: array
          items:
            $ref: "#/components/schemas/Permission"
            
    Permission:
      required:
        - id
        - name
        - description
      properties:
        id:
          description: "A unique identifier for this pemission"
          type: integer
          format: int64
        name:
          description: "The name of this permission"
          type: string
        description:
          description: "A short description of what the permission allows a user to do"
          type: string
          
    Users:
      type: array
      items:
        $ref: "#/components/schemas/User"
        
        
    BalanceHistoryItem:
      required:
        - id
        - amount
        - date
      properties:
        id:
          description: "A unique identifier for the balance"
          type: integer
          format: int64
        amount: 
          description: "The amound of money deposited or withdrawn"
          type: number
          format: double
        date:
          description: "The date of the balance change"
          type: string
          format: date
          
    BalanceHistoryItems:
      type: array
      items:
        $ref: "#/components/schemas/BalanceHistoryItem"
        
        
    PurchaseHistoryItem:
      required:
        - id
        - products
        - date
      properties:
        id:
          description: "A unique identifier for the purchase"
          type: integer
          format: int64
        products: 
          description: "A list of the products purchased"
          type: array
          items:
            $ref: "#/components/schemas/Product"
        date:
          description: "The date of the purchase"
          type: string
          format: date
        
    PurchaseHistoryItems:
      type: array
      items:
        $ref: "#/components/schemas/PurchaseHistoryItem"
        
        
    Product:
      required:
        - id
        - name
        - description
        - price
        - deposit
        - barcode
        - typeid
        - archived
      properties:
        id:
          description: "ID of the product"
          type: integer
          format: int64
        name:
          description: "The name of the product"
          type: string
        description:
          description: "A short description of the product"
          type: string
        price:
          description: "The price of the product"
          type: number
          format: double
        deposit:
          description: "The desposit of the product (only for drinks)"
          type: number
          format: double
        barcode:
          description: "A string representation of the barcode"
          type: integer
          format: string
          pattern: ^[0-9]+&
        typeid:
          description: "A unique identifier for the product type"
          type: array
          items:
            type: integer
        archived:
          description: "Indicates if the product has been archived"
          type: boolean
            
    Products:
      type: array
      items:
        $ref: "#/components/schemas/Product"
        
        
    Error:
      required:
        - code
        - message
      properties:
        code:
          description: "A code for the error"
          type: integer
          format: int32
        message:
          description: "A description of the error"
          type: string