{
  "_comment": "Example API definition for version 1",
  "api_name": "User Management API",
  "version": "1.0",
  "description": "API for managing user accounts and profiles.",
  "base_path": "/api/v1",
  "endpoints": [
    {
      "path": "/users",
      "method": "GET",
      "description": "Retrieve a list of all users.",
      "parameters": [
        {
          "name": "limit",
          "type": "integer",
          "description": "Maximum number of users to return.",
          "required": false,
          "default": 20
        },
        {
          "name": "offset",
          "type": "integer",
          "description": "Offset for pagination.",
          "required": false,
          "default": 0
        }
      ],
      "responses": {
        "200": {
          "description": "Successful operation",
          "schema": {
            "type": "array",
            "items": {
              "$ref": "#/definitions/User"
            }
          }
        },
        "500": {
          "description": "Internal server error"
        }
      }
    },
    {
      "path": "/users/{user_id}",
      "method": "GET",
      "description": "Retrieve a specific user by ID.",
      "parameters": [
        {
          "name": "user_id",
          "type": "string",
          "description": "ID of the user to retrieve.",
          "required": true,
          "in": "path"
        }
      ],
      "responses": {
        "200": {
          "description": "Successful operation",
          "schema": {
            "$ref": "#/definitions/User"
          }
        },
        "404": {
          "description": "User not found"
        },
        "500": {
          "description": "Internal server error"
        }
      }
    },
    {
      "path": "/users",
      "method": "POST",
      "description": "Create a new user.",
      "parameters": [
        {
          "name": "user",
          "type": "object",
          "description": "User object to create.",
          "required": true,
          "in": "body",
          "schema": {
            "$ref": "#/definitions/CreateUserRequest"
          }
        }
      ],
      "responses": {
        "201": {
          "description": "User created successfully",
          "schema": {
            "$ref": "#/definitions/User"
          }
        },
        "400": {
          "description": "Invalid request body"
        },
        "500": {
          "description": "Internal server error"
        }
      }
    },
    {
      "path": "/users/{user_id}",
      "method": "PUT",
      "description": "Update an existing user.",
      "parameters": [
        {
          "name": "user_id",
          "type": "string",
          "description": "ID of the user to update.",
          "required": true,
          "in": "path"
        },
        {
          "name": "user",
          "type": "object",
          "description": "User object with updated information.",
          "required": true,
          "in": "body",
          "schema": {
            "$ref": "#/definitions/UpdateUserRequest"
          }
        }
      ],
      "responses": {
        "200": {
          "description": "User updated successfully",
          "schema": {
            "$ref": "#/definitions/User"
          }
        },
        "400": {
          "description": "Invalid request body"
        },
        "404": {
          "description": "User not found"
        },
        "500": {
          "description": "Internal server error"
        }
      }
    },
    {
      "path": "/users/{user_id}",
      "method": "DELETE",
      "description": "Delete a user.",
      "parameters": [
        {
          "name": "user_id",
          "type": "string",
          "description": "ID of the user to delete.",
          "required": true,
          "in": "path"
        }
      ],
      "responses": {
        "204": {
          "description": "User deleted successfully"
        },
        "404": {
          "description": "User not found"
        },
        "500": {
          "description": "Internal server error"
        }
      }
    }
  ],
  "definitions": {
    "User": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier for the user."
        },
        "username": {
          "type": "string",
          "description": "Username of the user."
        },
        "email": {
          "type": "string",
          "description": "Email address of the user."
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "description": "Timestamp of when the user was created."
        },
        "updated_at": {
          "type": "string",
          "format": "date-time",
          "description": "Timestamp of when the user was last updated."
        }
      },
      "required": [
        "id",
        "username",
        "email",
        "created_at",
        "updated_at"
      ]
    },
    "CreateUserRequest": {
      "type": "object",
      "properties": {
        "username": {
          "type": "string",
          "description": "Username of the user."
        },
        "email": {
          "type": "string",
          "description": "Email address of the user."
        },
        "password": {
          "type": "string",
          "description": "Password for the user."
        }
      },
      "required": [
        "username",
        "email",
        "password"
      ]
    },
    "UpdateUserRequest": {
      "type": "object",
      "properties": {
        "username": {
          "type": "string",
          "description": "Username of the user."
        },
        "email": {
          "type": "string",
          "description": "Email address of the user."
        }
      }
    }
  }
}