138 lines
4.2 KiB
JSON
138 lines
4.2 KiB
JSON
{
|
|
"_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."
|
|
}
|
|
}
|
|
}
|
|
]
|
|
} |