openapi: 3.1.0
info:
title: User Management API
description: A simple API for managing users
version: '1.0.0'
components:
schemas:
User:
type: object
properties:
id:
type: string
format: uuid
description: Unique identifier for the user
example: "123e4567-e89b-12d3-a456-426614174000"
name:
type: string
description: Full name of the user
minLength: 1
maxLength: 100
example: "John Doe"
email:
type: string
format: email
description: Email address of the user
example: "john.doe@example.com"
age:
type: integer
description: Age of the user
minimum: 0
maximum: 150
example: 30
created_at:
type: string
format: date-time
description: When the user was created
example: "2023-01-01T00:00:00Z"
is_active:
type: boolean
description: Whether the user is active
example: true
tags:
type: array
items:
type: string
description: Tags associated with the user
minItems: 0
maxItems: 10
example: [ "admin", "verified" ]
required:
- id
- name
- email
CreateUserRequest:
type: object
properties:
name:
type: string
description: Full name of the user
minLength: 1
maxLength: 100
example: "John Doe"
email:
type: string
format: email
description: Email address of the user
example: "john.doe@example.com"
age:
type: integer
description: Age of the user
minimum: 0
maximum: 150
example: 30
tags:
type: array
items:
type: string
description: Tags associated with the user
minItems: 0
maxItems: 10
example: [ "user" ]
required:
- name
- email
UpdateUserRequest:
type: object
properties:
name:
type: string
description: Full name of the user
minLength: 1
maxLength: 100
example: "John Smith"
email:
type: string
format: email
description: Email address of the user
example: "john.smith@example.com"
age:
type: integer
description: Age of the user
minimum: 0
maximum: 150
example: 31
is_active:
type: boolean
description: Whether the user is active
example: false
tags:
type: array
items:
type: string
description: Tags associated with the user
minItems: 0
maxItems: 10
example: [ "admin", "verified" ]
UserListResponse:
type: object
properties:
users:
type: array
items:
$ref: '#/components/schemas/User'
description: List of users
total:
type: integer
description: Total number of users
example: 100
page:
type: integer
description: Current page number
example: 1
limit:
type: integer
description: Number of users per page
example: 10
required:
- users
- total
- page
- limit
ErrorResponse:
type: object
properties:
error:
type: string
description: Error message
example: "User not found"
code:
type: string
description: Error code
example: "USER_NOT_FOUND"
details:
type: object
description: Additional error details
required:
- error
- code
parameters:
UserIdParam:
name: user_id
in: path
required: true
description: ID of the user
schema:
type: string
format: uuid
example: "123e4567-e89b-12d3-a456-426614174000"
PageParam:
name: page
in: query
required: false
description: Page number for pagination
schema:
type: integer
minimum: 1
default: 1
example: 1
LimitParam:
name: limit
in: query
required: false
description: Number of items per page
schema:
type: integer
minimum: 1
maximum: 100
default: 10
example: 10
SearchParam:
name: search
in: query
required: false
description: Search term for filtering users
schema:
type: string
minLength: 1
maxLength: 100
example: "john"
paths:
/users:
get:
summary: List users
description: Retrieve a paginated list of users
operationId: listUsers
tags:
- Users
parameters:
- $ref: '#/components/parameters/PageParam'
- $ref: '#/components/parameters/LimitParam'
- $ref: '#/components/parameters/SearchParam'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/UserListResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- bearerAuth: [ ]
post:
summary: Create user
description: Create a new user
operationId: createUser
tags:
- Users
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUserRequest'
responses:
'201':
description: User created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
description: User already exists
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- bearerAuth: [ ]
/users/{user_id}:
get:
summary: Get user by ID
description: Retrieve a specific user by their ID
operationId: getUserById
tags:
- Users
parameters:
- $ref: '#/components/parameters/UserIdParam'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'404':
description: User not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- bearerAuth: [ ]
put:
summary: Update user
description: Update an existing user
operationId: updateUser
tags:
- Users
parameters:
- $ref: '#/components/parameters/UserIdParam'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateUserRequest'
responses:
'200':
description: User updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: User not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- bearerAuth: [ ]
delete:
summary: Delete user
description: Delete a user by their ID
operationId: deleteUser
tags:
- Users
parameters:
- $ref: '#/components/parameters/UserIdParam'
responses:
'204':
description: User deleted successfully
'404':
description: User not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- bearerAuth: [ ]