# OpenAPI 3.0.3 specification for example API
openapi: 3.0.3

# API information
info:
  title: Example API
  version: 1.0.0
  description: This is a sample API definition for demonstration purposes.
  termsOfService: https://www.example.com/terms/
  contact:
    name: API Support
    url: https://www.example.com/support
    email: support@example.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

# Server URLs
servers:
  - url: https://api.example.com/v1
    description: Production server
  - url: https://staging.api.example.com/v1
    description: Staging server

# Paths (API endpoints)
paths:
  /users:
    get:
      summary: Get all users
      description: Returns a list of all users.
      operationId: getUsers
      tags:
        - Users
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '500':
          description: Internal server error
    post:
      summary: Create a new user
      description: Creates a new user with the provided information.
      operationId: createUser
      tags:
        - Users
      requestBody:
        description: User object to be created
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreate'
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Invalid input
        '500':
          description: Internal server error

  /users/{userId}:
    get:
      summary: Get a user by ID
      description: Returns a single user based on the provided ID.
      operationId: getUserById
      tags:
        - Users
      parameters:
        - name: userId
          in: path
          description: ID of the user to retrieve
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User not found
        '500':
          description: Internal server error
    put:
      summary: Update a user by ID
      description: Updates an existing user with the provided information.
      operationId: updateUser
      tags:
        - Users
      parameters:
        - name: userId
          in: path
          description: ID of the user to update
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        description: User object to be updated
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdate'
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Invalid input
        '404':
          description: User not found
        '500':
          description: Internal server error
    delete:
      summary: Delete a user by ID
      description: Deletes a user based on the provided ID.
      operationId: deleteUser
      tags:
        - Users
      parameters:
        - name: userId
          in: path
          description: ID of the user to delete
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '204':
          description: User deleted successfully (no content)
        '404':
          description: User not found
        '500':
          description: Internal server error

# Components (reusable schemas, parameters, etc.)
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier for the user
        username:
          type: string
          description: User's username
        email:
          type: string
          format: email
          description: User's email address
        firstName:
          type: string
          description: User's first name
        lastName:
          type: string
          description: User's last name
        createdAt:
          type: string
          format: date-time
          description: Date and time the user was created
      required:
        - id
        - username
        - email
    UserCreate:
      type: object
      properties:
        username:
          type: string
          description: User's username
        email:
          type: string
          format: email
          description: User's email address
        firstName:
          type: string
          description: User's first name
        lastName:
          type: string
          description: User's last name
        password:
          type: string
          description: User's password (REPLACE_ME - consider security best practices)
      required:
        - username
        - email
        - password
    UserUpdate:
      type: object
      properties:
        username:
          type: string
          description: User's username
        email:
          type: string
          format: email
          description: User's email address
        firstName:
          type: string
          description: User's first name
        lastName:
          type: string
          description: User's last name

  securitySchemes:
    bearerAuth:            # Define a security scheme for JWT authentication
      type: http
      scheme: bearer
      bearerFormat: JWT

# Security requirements for the API
security:
  - bearerAuth: []      # Apply the JWT authentication scheme globally

# Tags (for grouping operations)
tags:
  - name: Users
    description: Operations related to users