openapi.yaml

openapi: 3.0.0
info:
  title: Authorization Microservice
  version: 1.0.0
  description: Authorization microservice for medical consultation application. Handles the authorization of users for the entire application.

servers:
  - url: http://localhost:3001/api/v1
    description: Development server
  - url: /api/v1
    description: Production server

paths:
  /users:
    post:
      summary: Create User
      description: Creates a new user with specified roles, email, and associated IDs for doctor or patient.
      tags:
        - Users
      security:
        - cookieAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  description: Email address of the user.
                  example: "new_user@example.com"
                password:
                  type: string
                  description: User's password.
                  example: "securepassword123"
                roles:
                  type: array
                  description: List of roles assigned to the user.
                  items:
                    type: string
                  example: ["admin", "doctor"]
                doctorid:
                  type: string
                  description: Unique ID if the user is a doctor.
                  example: "doctor123"
                  nullable: true
                patientid:
                  type: string
                  description: Unique ID if the user is a patient.
                  example: "patient456"
                  nullable: true
              required:
                - email
                - password
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  email:
                    type: string
                    example: "new_user@example.com"
                  roles:
                    type: array
                    items:
                      type: string
                    example: ["admin", "doctor"]
                  doctorid:
                    type: string
                    example: "doctor123"
                    nullable: true
                  patientid:
                    type: string
                    example: "patient456"
                    nullable: true
        '400':
          description: Bad request - missing fields or user already exists
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
                example:
                  email: "Email is required"
                  password: "Password is required"
        '401':
          description: Unauthorized - token missing or invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "No token provided"
        '403':
          description: Forbidden - insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Forbidden"
        '500':
          $ref: '#/components/responses/ServerError'
  /users/{id}:
    get:
      summary: Retrieve user information
      description: Retrieve user details by user ID. Requires the user to be the owner or have specific roles.
      tags:
        - Users
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: ID of the user to retrieve
      responses:
        '200':
          description: User retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  _id:
                    type: string
                  email:
                    type: string
                  username:
                    type: string
                  roles:
                    type: array
                    items:
                      type: string
                  createdAt:
                    type: string
                    format: date-time
                  updatedAt:
                    type: string
                    format: date-time
              example:
                _id: "617f1f77bcf86cd799439011"
                email: "user@example.com"
                username: "johndoe"
                roles: ["user"]
                createdAt: "2023-01-01T12:00:00Z"
                updatedAt: "2023-01-10T12:00:00Z"
        '401':
          description: Unautenticated
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: "Token not valid"
        '403':
          description: Unauthorized access
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: "Forbidden"
        '404':
          description: User not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: "User not found"
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: "Internal server error"
    put:
      summary: Update user information
      description: Update user details by user ID. Requires the user to be the owner or have specific roles.
      tags:
        - Users
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: ID of the user to update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  description: Email address of the user.
                  example: "user@example.com"
                password:
                  type: string
                  description: User's password.
                  example: "securepassword123"
                roles:
                  type: array
                  description: List of roles assigned to the user.
                  items:
                    type: string
                  example: ["admin", "doctor"]
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  _id:
                    type: string
                  email:
                    type: string
                  roles:
                    type: array
                    items:
                      type: string
                  createdAt:
                    type: string
                    format: date-time
                  updatedAt:
                    type: string
                    format: date-time
              example:
                _id: "617f1f77bcf86cd799439011"
                email: "user@example.com"
                roles: ["doctor"]
                createdAt: "2023-01-01T12:00:00Z"
                updatedAt: "2023-01-10T12:00:00Z"
        '400':
          description: Bad request - missing fields or user already exists
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
                example:
                  email: "Email is required"
                  password: "Password is required"
        '401':
          description: Unautenticated
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: "Token not valid"
        '403':
          description: Unauthorized access
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: "Forbidden"
        '404':
          description: User not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: "User not found"
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: "Internal server error"
    delete:
      summary: Deletes user
      description: Delete user by user ID. Requires the user to have specific roles.
      tags:
        - Users
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: ID of the user to update
      responses:
        '204':
          description: User deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  _id:
                    type: string
              example:
                _id: "617f1f77bcf86cd799439011"
        '401':
          description: Unautenticated
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: "Token not valid"
        '403':
          description: Unauthorized access
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: "Unauthorized"
        '404':
          description: User not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: "User not found"
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: "Internal server error"

  /users/change-password:
    post:
      summary: Change user password
      description: Allows authenticated users to change their password.
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                currentPassword:
                  type: string
                  description: The current password of the user.
                  example: "oldPassword123"
                newPassword:
                  type: string
                  description: The new password to set.
                  example: "newPassword456"
              required:
                - currentPassword
                - newPassword
      responses:
        '200':
          description: Password changed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Password changed successfully"
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: ""
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Unauthorized"
        '403':
          description: Unauthorized access
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: "Forbidden"
        '404':
          description: User not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: "User not found"
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Error when authenticating" 

  /users/enable-2fa:
    post:
      summary: Enable two-factor authentication
      description: Allows authenticated users to enable two-factor authentication.
      tags:
        - Users
      responses:
        '200':
          description: 2FA successfully enabled
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "2FA enabled successfully"
                  qrCodeUrl:
                    type: string
                    format: uri
                    example: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
                  secret:
                    type: string
                    example: "JBSWY3DPEHPK3PXP"
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Bad request"
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Unauthorized"
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Internal server error"

  /users/verify-2fa:
    post:
      summary: Verify two-factor authentication
      description: Allows authenticated users to verify two-factor authentication.
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: string
                  description: The user's unique ID.
                  example: "550e8400-e29b-41d4-a716-446655440000"
                totpToken:
                  type: string
                  description: The two-factor authentication token.
                  example: "123456"
              required:
                - userId
                - totpToken
      responses:
        '200':
          description: 2FA token verified successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Login successful"
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "2FA not enabled for this user"
        '403':
          description: Unauthorized access
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: "Invalid 2FA token"
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Internal server error"
  /login:
    post:
      summary: User Login
      description: Authenticates a user with their email and password.
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  description: The user's unique email.
                  example: "admin@email.com"
                password:
                  type: string
                  description: The user's password.
                  example: "admin123"
              required:
                - email
                - password
      responses:
        '200':
          description: Successful login
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Login successful"
        '401':
          description: Unauthorized - invalid credentials
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Invalid credentials"
        '500':
          $ref: '#/components/responses/ServerError'

  /logout:
    post:
      summary: User Logout
      description: Logs out a user by clearing authentication tokens.
      tags:
        - Authentication
      responses:
        '200':
          description: Successful logout
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Logout successful"
        '401':
          description: Unauthorized - user is not logged in
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Not logged in"
        '500':
          $ref: '#/components/responses/ServerError'

  /token/refresh:
    get:
      summary: Refreshes the user's token.
      description: Refreshes the user's auth and refresh tokens and sets new values in cookies.
      tags:
        - Authentication
      operationId: validateAuthToken
      responses:
        '200':
          description: Tokens refreshed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Tokens refreshed
        '401':
          description: Unauthorized - Token is missing, expired, or invalid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Token expired or invalid.

  /token/validate:
    get:
      summary: Validates the user's token.
      description: Checks the validity of the token provided in the user's cookies.
      tags:
        - Authentication
      operationId: validateAuthToken
      responses:
        '200':
          description: Token is valid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Token is valid
        '401':
          description: Unauthorized - Token is missing, expired, or invalid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Token expired or invalid.

components:
  schemas:
    User:
      type: object
      properties:
        _id:
          type: string
          format: uuid
          description: Unique identifier for the user. Defaults to a generated UUID.
          example: "550e8400-e29b-41d4-a716-446655440000"
        email:
          type: string
          description: Unique email for the user.
          example: "john_doe@email.com"
        password:
          type: string
          description: Hashed password of the user.
        roles:
          type: array
          description: List of roles assigned to the user.
          items:
            type: string
            enum:
              - admin
              - clinicadmin
              - doctor
              - patient
          default: ["patient"]
          example: ["doctor", "clinicadmin"]
        doctorid:
          type: string
          nullable: true
          description: Identifier of the doctor if the user is a clinic doctor.
          example: "doctor12345"
        patientid:
          type: string
          nullable: true
          description: Identifier of the patient if the user is associated with a patient record.
          example: "patient12345"
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the user was created.
          example: "2023-10-25T08:40:51.620Z"
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the user was last updated.
          example: "2023-10-26T08:40:51.620Z"
      required:
        - email
        - password
        - roles
      description: Schema for the User model, including fields for unique ID, email, password, role, and optional associations with patient and clinic.

  securitySchemes:
    cookieAuth:
        type: apiKey
        in: cookie
        name: token
    # Define any security schemes if relevant (e.g., JWT authentication).

  # Add other reusable components here (e.g., responses, request bodies).
  responses:
    ServerError:
      description: Server error
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: "Server error"