Skip to content

openapi.md

Latest commit

 

History

History
720 lines (505 loc) · 8.86 KB

openapi.md

File metadata and controls

720 lines (505 loc) · 8.86 KB
Raw

Authorization Microservice

Version 1.0.0

Authorization microservice for medical consultation application. Handles the authorization of users for the entire application.

Path Table

Method Path Description
POST /login User Login
POST /logout User Logout
GET /token/refresh Refreshes the user's token.
GET /token/validate Validates the user's token.
POST /users Create User
POST /users/change-password Change user password
POST /users/enable-2fa Enable two-factor authentication
POST /users/verify-2fa Verify two-factor authentication
DELETE /users/{id} Deletes user
GET /users/{id} Retrieve user information
PUT /users/{id} Update user information

Reference Table

Name Path Description
ServerError #/components/responses/ServerError Server error
User #/components/schemas/User Schema for the User model, including fields for unique ID, email, password, role, and optional associations with patient and clinic.
cookieAuth #/components/securitySchemes/cookieAuth

Path Details

[POST]/login

  • Summary
    User Login

  • Description
    Authenticates a user with their email and password.

RequestBody

  • application/json
{
  // The user's unique email.
  email: string
  // The user's password.
  password: string
}

Responses

  • 200 Successful login

application/json

{
  message?: string
}
  • 401 Unauthorized - invalid credentials

application/json

{
  message?: string
}
  • 500 undefined

[POST]/logout

  • Summary
    User Logout

  • Description
    Logs out a user by clearing authentication tokens.

Responses

  • 200 Successful logout

application/json

{
  message?: string
}
  • 401 Unauthorized - user is not logged in

application/json

{
  message?: string
}
  • 500 undefined

[GET]/token/refresh

  • Summary
    Refreshes the user's token.

  • Description
    Refreshes the user's auth and refresh tokens and sets new values in cookies.

Responses

  • 200 Tokens refreshed.

application/json

{
  message?: string
}
  • 401 Unauthorized - Token is missing, expired, or invalid.

application/json

{
  message?: string
}

[GET]/token/validate

  • Summary
    Validates the user's token.

  • Description
    Checks the validity of the token provided in the user's cookies.

Responses

  • 200 Token is valid.

application/json

{
  message?: string
}
  • 401 Unauthorized - Token is missing, expired, or invalid.

application/json

{
  message?: string
}

[POST]/users

  • Summary
    Create User

  • Description
    Creates a new user with specified roles, email, and associated IDs for doctor or patient.

  • Security
    cookieAuth

RequestBody

  • application/json
{
  // Email address of the user.
  email: string
  // User's password.
  password: string
  roles?: string[]
  // Unique ID if the user is a doctor.
  doctorid?: string
  // Unique ID if the user is a patient.
  patientid?: string
}

Responses

  • 201 User created successfully

application/json

{
  email?: string
  roles?: string[]
  doctorid?: string
  patientid?: string
}
  • 400 Bad request - missing fields or user already exists

application/json

{
}
  • 401 Unauthorized - token missing or invalid

application/json

{
  message?: string
}
  • 403 Forbidden - insufficient permissions

application/json

{
  message?: string
}
  • 500 undefined

[POST]/users/change-password

  • Summary
    Change user password

  • Description
    Allows authenticated users to change their password.

RequestBody

  • application/json
{
  // The current password of the user.
  currentPassword: string
  // The new password to set.
  newPassword: string
}

Responses

  • 200 Password changed successfully

application/json

{
  message?: string
}
  • 400 Invalid request

application/json

{
  message?: string
}
  • 401 Unauthorized

application/json

{
  message?: string
}
  • 403 Unauthorized access

application/json

{
  message?: string
}
  • 404 User not found

application/json

{
  message?: string
}
  • 500 Internal server error

application/json

{
  message?: string
}

[POST]/users/enable-2fa

  • Summary
    Enable two-factor authentication

  • Description
    Allows authenticated users to enable two-factor authentication.

Responses

  • 200 2FA successfully enabled

application/json

{
  message?: string
  qrCodeUrl?: string
  secret?: string
}
  • 400 Invalid request

application/json

{
  message?: string
}
  • 401 Unauthorized

application/json

{
  message?: string
}
  • 500 Internal server error

application/json

{
  message?: string
}

[POST]/users/verify-2fa

  • Summary
    Verify two-factor authentication

  • Description
    Allows authenticated users to verify two-factor authentication.

RequestBody

  • application/json
{
  // The user's unique ID.
  userId: string
  // The two-factor authentication token.
  totpToken: string
}

Responses

  • 200 2FA token verified successfully

application/json

{
  message?: string
}
  • 400 Invalid request

application/json

{
  message?: string
}
  • 403 Unauthorized access

application/json

{
  message?: string
}
  • 500 Internal server error

application/json

{
  message?: string
}

[DELETE]/users/{id}

  • Summary
    Deletes user

  • Description
    Delete user by user ID. Requires the user to have specific roles.

Responses

  • 204 User deleted successfully

application/json

{
  _id?: string
}
  • 401 Unautenticated

application/json

{
  message?: string
}
  • 403 Unauthorized access

application/json

{
  message?: string
}
  • 404 User not found

application/json

{
  message?: string
}
  • 500 Internal server error

application/json

{
  message?: string
}

[GET]/users/{id}

  • Summary
    Retrieve user information

  • Description
    Retrieve user details by user ID. Requires the user to be the owner or have specific roles.

Responses

  • 200 User retrieved successfully

application/json

{
  _id?: string
  email?: string
  username?: string
  roles?: string[]
  createdAt?: string
  updatedAt?: string
}
  • 401 Unautenticated

application/json

{
  message?: string
}
  • 403 Unauthorized access

application/json

{
  message?: string
}
  • 404 User not found

application/json

{
  message?: string
}
  • 500 Internal server error

application/json

{
  message?: string
}

[PUT]/users/{id}

  • Summary
    Update user information

  • Description
    Update user details by user ID. Requires the user to be the owner or have specific roles.

RequestBody

  • application/json
{
  // Email address of the user.
  email?: string
  // User's password.
  password?: string
  roles?: string[]
}

Responses

  • 200 User updated successfully

application/json

{
  _id?: string
  email?: string
  roles?: string[]
  createdAt?: string
  updatedAt?: string
}
  • 400 Bad request - missing fields or user already exists

application/json

{
}
  • 401 Unautenticated

application/json

{
  message?: string
}
  • 403 Unauthorized access

application/json

{
  message?: string
}
  • 404 User not found

application/json

{
  message?: string
}
  • 500 Internal server error

application/json

{
  message?: string
}

References

#/components/responses/ServerError

  • application/json
{
  message?: string
}

#/components/schemas/User

// Schema for the User model, including fields for unique ID, email, password, role, and optional associations with patient and clinic.
{
  // Unique identifier for the user. Defaults to a generated UUID.
  _id?: string
  // Unique email for the user.
  email: string
  // Hashed password of the user.
  password: string
  roles?: enum[admin, clinicadmin, doctor, patient][]
  // Identifier of the doctor if the user is a clinic doctor.
  doctorid?: string
  // Identifier of the patient if the user is associated with a patient record.
  patientid?: string
  // Timestamp when the user was created.
  createdAt?: string
  // Timestamp when the user was last updated.
  updatedAt?: string
}

#/components/securitySchemes/cookieAuth

{
  "type": "apiKey",
  "in": "cookie",
  "name": "token"
}