swagger.yaml

openapi: 3.0.0
info:
  title: Api-Template-With-Auth 🔐
  version: 1.0.0
  description: A robust and versatile REST API template with the setup of Authentication and User Management to streamline the process of creating REST APIs using Express.js & MongoDB.
servers:
  - url: http://localhost:3000/api/v1
    description: Local server

paths:
  # Seed Routes
  /seed/users:
    post:
      summary: Seed Users
      tags: [SEED Routes]
      responses:
        "201":
          description: Users added successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  statusCode:
                    type: number
                    example: 200
                  data:
                    type: object
                    properties:
                      users:
                        type: array
                        items:
                          type: object
                          properties:
                            fullName:
                              type: string
                            username:
                              type: string
                            email:
                              type: string
                    example:
                      users: [user 1, user 2, user 3]
  
  # Auth Api's
  /auth/register:
    post:
      summary: Register a new user
      tags: [Auth]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - fullName
                - username
                - email
                - password
              properties:
                fullName:
                  type: string
                username:
                  type: string
                email:
                  type: string
                password:
                  type: string
                avatar:
                  type: binary
      responses:
        "201":
          description: User registered successfully.
        "400":
          description: Invalid input.

  /auth/login:
    post:
      summary: Login a user
      tags: [Auth]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email/username
                - password
              properties:
                email:
                  type: string
                username:
                  type: string
                password:
                  type: string
      responses:
        "200":
          description: User logged in successfully
        "400":
          description: Invalid input

  /auth/refresh-token:
    patch:
      summary: Refresh access token
      tags: [Auth]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - refreshToken
                - userId
              properties:
                refreshToken:
                  type: string
                userId:
                  type: string
      responses:
        "200":
          description: Access token refreshed successfully
        "400":
          description: Invalid input
        "401":
          description: The refresh token provided is invalid or has expired

  # Users Management Api's
  /users/confirm-account:
    get:
      summary: Confirm user account
      tags: [Users]
      parameters:
        - name: userId
          in: query
          required: true
          schema:
            type: string
        - name: confirmationToken
          in: query
          required: true
          schema:
            type: string

      responses:
        "200":
          description: Account confirmed successfully
        "400":
          description: Invalid input
        "404":
          description: User not found
        "401":
          description: Token is invalid or has expired

  /users/resend-confirmation-email:
    get:
      summary: Resend confirmation email
      tags: [Users]
      parameters:
        - name: email
          in: query
          required: true
          schema:
            type: string

      responses:
        "200":
          description: Confirmation email resent successfully
        "400":
          description: Invalid input

  /users/forgot-password:
    get:
      summary: Request password reset
      tags: [Users]
      parameters:
        - name: email
          in: query
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Password reset link sent successfully
        "400":
          description: Invalid email address

  /users/reset-password:
    post:
      summary: Reset password
      tags: [Users]
      parameters:
        - name: userId
          in: query
          required: true
          schema:
            type: string
        - name: resetPasswordToken
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                newPassword:
                  type: string
                confirmPassword:
                  type: string
      responses:
        "200":
          description: Password reset successfully
        "400":
          $ref: "#/components/responses/InvalidInput"
        "401":
          $ref: "#/components/responses/TokenInvalidOrExpired"
        "404":
          $ref: "#/components/responses/UserNotFound"

  /users/change-email:
    put:
      summary: Change user email
      tags: [Users]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                newEmail:
                  type: string
                password:
                  type: string
      responses:
        "200":
          description: Email change request sent successfully
        "400":
          $ref: "#/components/responses/InvalidInput"
        "401":
          $ref: "#/components/responses/TokenInvalidOrExpired"
        "409":
          description: New email is already in use by someone else. Please try a different email

  /users/confirm-change-email:
    patch:
      summary: Confirm email change
      tags: [Users]
      requestBody:
        required: true
        parameters:
          - name: userId
            in: query
            required: true
            schema:
              type: string
          - name: confirmationToken
            in: query
            required: true
            schema:
              type: string
      responses:
        "200":
          description: Email changed successfully
        "400":
          $ref: "#/components/responses/InvalidInput"
        "401":
          $ref: "#/components/responses/TokenInvalidOrExpired"

  /users/change-password:
    patch:
      summary: Change user password
      tags: [Users]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                oldPassword:
                  type: string
                newPassword:
                  type: string
                confirmPassword:
                  type: string
      responses:
        "200":
          description: Password changed successfully
        "400":
          $ref: "#/components/responses/InvalidInput"
        "401":
          $ref: "#/components/responses/TokenInvalidOrExpired"

  /users:
    get:
      summary: Get all users (admin only)
      tags: [Users]
      security:
        - bearerAuth: ["admin"]
      responses:
        "200":
          description: List of all users retrieved successfully
        "403":
          description: Forbidden

  /users/{id}:
    get:
      summary: Get single user (admin & logged-in user)
      tags: [Users]
      security:
        - bearerAuth: []
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: User details retrieved successfully
        "400":
          $ref: "#/components/responses/InvalidInput"
        "401":
          $ref: "#/components/responses/TokenInvalidOrExpired"
        "403":
          description: Forbidden

    put:
      summary: Update account details (logged-in user)
      tags: [Users]
      security:
        - bearerAuth: []
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                fullName:
                  type: string
                username:
                  type: string
      responses:
        "200":
          description: User details updated successfully
        "400":
          $ref: "#/components/responses/InvalidInput"
        "401":
          $ref: "#/components/responses/TokenInvalidOrExpired"
        "409":
          description: Username is already in use by someone else. Please try a different username

    delete:
      summary: Delete account (admin only)
      tags: [Users]
      security:
        - bearerAuth: []
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: User account deleted successfully
        "400":
          $ref: "#/components/responses/InvalidInput"
        "401":
          $ref: "#/components/responses/TokenInvalidOrExpired"
        "403":
          description: Forbidden

  /users/profile/{id}:
    get:
      summary: Get user profile (public)
      tags: [Users]
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: User profile retrieved successfully
        "400":
          $ref: "#/components/responses/InvalidInput"

  /users/manage-user-status/{userid}:
    patch:
      summary: Manage user status (admin only [ban/unban] user)
      tags: [Users]
      security:
        - bearerAuth: []
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
        - name: action
          in: query
          required: true
          schema:
            type: string
            enum: [ban, unban] # Adding required values for the action parameter
      responses:
        "200":
          description: User status updated successfully
        "400":
          $ref: "#/components/responses/InvalidInput"
        "401":
          $ref: "#/components/responses/TokenInvalidOrExpired"
        "403":
          description: Forbidden


components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
  responses:
    InvalidInput:
      description: Invalid input
    UserNotFound:
      description: User not found
    TokenInvalidOrExpired:
      description: Token is invalid or has expired