{
  "_comment": "Example API Definition - Version 2.0",
  "api_name": "MyAwesomeAPI",
  "version": "2.0",
  "description": "This is the second version of the MyAwesomeAPI, introducing enhanced features and improved performance.",
  "base_url": "https://api.example.com/v2",
  "endpoints": [
    {
      "_comment": "Endpoint for retrieving user data",
      "path": "/users/{user_id}",
      "method": "GET",
      "description": "Retrieves user information based on the provided user ID.",
      "parameters": [
        {
          "name": "user_id",
          "in": "path",
          "description": "The unique identifier of the user.",
          "required": true,
          "type": "integer"
        },
        {
          "name": "include_details",
          "in": "query",
          "description": "Whether to include additional user details (e.g., address, phone number).",
          "required": false,
          "type": "boolean",
          "default": false
        }
      ],
      "responses": {
        "200": {
          "description": "Successful retrieval of user data.",
          "schema": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer",
                "description": "The user's unique identifier."
              },
              "username": {
                "type": "string",
                "description": "The user's username."
              },
              "email": {
                "type": "string",
                "description": "The user's email address."
              },
              "first_name": {
                "type": "string",
                "description": "The user's first name."
              },
              "last_name": {
                "type": "string",
                "description": "The user's last name."
              },
              "address": {
                "type": "string",
                "description": "The user's address (optional, only included if include_details=true)"
              },
              "phone_number": {
                "type": "string",
                "description": "The user's phone number (optional, only included if include_details=true)"
              }
            }
          }
        },
        "404": {
          "description": "User not found."
        }
      }
    },
    {
      "_comment": "Endpoint for creating a new user",
      "path": "/users",
      "method": "POST",
      "description": "Creates a new user account.",
      "requestBody": {
        "description": "User data to create a new account.",
        "required": true,
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "username": {
                  "type": "string",
                  "description": "The desired username.",
                  "required": true
                },
                "password": {
                  "type": "string",
                  "description": "The desired password.",
                  "required": true
                },
                "email": {
                  "type": "string",
                  "description": "The user's email address.",
                  "required": true
                },
                 "first_name": {
                  "type": "string",
                  "description": "The user's first name.",
                  "required": false
                },
                "last_name": {
                  "type": "string",
                  "description": "The user's last name.",
                  "required": false
                }
              }
            }
          }
        }
      },
      "responses": {
        "201": {
          "description": "User account created successfully.",
          "schema": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer",
                "description": "The newly created user's unique identifier."
              },
              "username": {
                "type": "string",
                "description": "The user's username."
              }
            }
          }
        },
        "400": {
          "description": "Invalid request body or validation errors."
        }
      }
    }
  ]
}