autostore/openapi.yaml

openapi: 3.0.3
info:
  title: AutoStore API
  description: API for the AutoStore system - a system to store items with expiration dates that automatically orders new items when they expire.
  version: 1.0.0
servers:
  - url: http://localhost:3000/api/v1
    description: Development server
paths:
  /register:
    post:
      summary: Register a new user
      description: Creates a new user account and returns a JWT token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - username
                - password
              properties:
                username:
                  type: string
                  description: User's username or email
                password:
                  type: string
                  description: User's password
      responses:
        '201':
          description: User successfully registered
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/JsendSuccess'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          user:
                            $ref: '#/components/schemas/User'
                          token:
                            type: string
                            description: JWT token for authentication
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsendError'
        '409':
          description: Username already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsendError'

  /login:
    post:
      summary: User login
      description: Authenticates a user and returns a JWT token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - username
                - password
              properties:
                username:
                  type: string
                  description: User's username or email
                password:
                  type: string
                  description: User's password
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/JsendSuccess'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          user:
                            $ref: '#/components/schemas/User'
                          token:
                            type: string
                            description: JWT token for authentication
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsendError'

  /users:
    get:
      summary: Get list of users
      description: Returns a list of all users (requires authentication)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of users
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/JsendSuccess'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/User'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsendError'

  /users/{id}:
    get:
      summary: Get user by ID
      description: Returns a specific user by their ID (requires authentication)
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: User ID
          schema:
            type: string
      responses:
        '200':
          description: User details
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/JsendSuccess'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/User'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsendError'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsendError'
    post:
      summary: Create a new user
      description: Creates a new user (admin functionality, requires authentication)
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: User ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserInput'
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/JsendSuccess'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/User'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsendError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsendError'
        '409':
          description: User already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsendError'
    put:
      summary: Update a user
      description: Updates an existing user (requires authentication)
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: User ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserInput'
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/JsendSuccess'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/User'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsendError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsendError'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsendError'
    delete:
      summary: Delete a user
      description: Deletes an existing user (requires authentication)
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: User ID
          schema:
            type: string
      responses:
        '204':
          description: User deleted successfully
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsendError'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsendError'

  /items:
    get:
      summary: Get list of items
      description: Returns a list of all items for the authenticated user
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of items
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/JsendSuccess'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Item'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsendError'
    post:
      summary: Create a new item
      description: Creates a new item for the authenticated user
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ItemInput'
      responses:
        '201':
          description: Item created successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/JsendSuccess'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/Item'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsendError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsendError'

  /items/{id}:
    get:
      summary: Get item by ID
      description: Returns a specific item by its ID
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Item ID
          schema:
            type: string
      responses:
        '200':
          description: Item details
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/JsendSuccess'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/Item'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsendError'
        '404':
          description: Item not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsendError'
    put:
      summary: Update an item
      description: Updates an existing item
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Item ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ItemInput'
      responses:
        '200':
          description: Item updated successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/JsendSuccess'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/Item'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsendError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsendError'
        '404':
          description: Item not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsendError'
    delete:
      summary: Delete an item
      description: Deletes an existing item
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Item ID
          schema:
            type: string
      responses:
        '204':
          description: Item deleted successfully
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsendError'
        '404':
          description: Item not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsendError'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    JsendSuccess:
      type: object
      properties:
        status:
          type: string
          example: success
        data:
          type: object
          description: Response data

    JsendError:
      type: object
      properties:
        status:
          type: string
          example: error
        message:
          type: string
          description: Error message
        code:
          type: integer
          description: Error code
        data:
          type: object
          description: Additional error data

    User:
      type: object
      properties:
        id:
          type: string
          description: User ID
        username:
          type: string
          description: User's username or email

    UserInput:
      type: object
      required:
        - username
        - password
      properties:
        username:
          type: string
          description: User's username or email
        password:
          type: string
          description: User's password

    Item:
      type: object
      properties:
        id:
          type: string
          description: Item ID
        name:
          type: string
          description: Item name
        expirationDate:
          type: string
          format: date-time
          description: Item expiration date
        orderUrl:
          type: string
          format: uri
          description: URL to send order request when item expires
        userId:
          type: string
          description: ID of the user who owns this item

    ItemInput:
      type: object
      required:
        - name
        - expirationDate
        - orderUrl
      properties:
        name:
          type: string
          description: Item name
        expirationDate:
          type: string
          format: date-time
          description: Item expiration date
        orderUrl:
          type: string
          format: uri
          description: URL to send order request when item expires