Generate professional REST API endpoint documentation.
Clear API documentation is essential for developers to understand and use your API effectively. Follow these best practices for professional API documentation.
Clearly explain what the endpoint does:
Document how to authenticate:
| Parameter Type | Location | Example |
|---|---|---|
| Path Parameters | In URL path | /users/{id} |
| Query Parameters | After ? in URL | /users?page=1&limit=10 |
| Request Body | HTTP body (POST/PUT) | {"name": "John"} |
| Headers | HTTP headers | Authorization: Bearer token |
Document all possible responses including:
## POST /api/v1/users
Creates a new user account.
**Authentication:** Bearer Token (requires `users:write` scope)
### Request Body
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| name | string | Yes | User's full name (2-100 chars) |
| email | string | Yes | Valid email address |
| role | string | No | User role (default: "user") |
### Example Request
```bash
curl -X POST https://api.example.com/api/v1/users \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"name": "John Doe",
"email": "john@example.com",
"role": "admin"
}'
```
### Responses
**201 Created**
```json
{
"id": "usr_123456",
"name": "John Doe",
"email": "john@example.com",
"role": "admin",
"created_at": "2024-03-15T10:30:00Z"
}
```
**400 Bad Request**
```json
{
"error": "validation_error",
"message": "Invalid email format",
"fields": {
"email": "Must be a valid email address"
}
}
```
**401 Unauthorized**
```json
{
"error": "unauthorized",
"message": "Invalid or expired token"
}
```Success:
Client Errors:
Server Errors: