openapi: 3.0.0
info:
title: Users API
version: 2.0.0
description: API for managing user accounts and profiles within the system. It supports operations like retrieving, creating, and viewing individual users.
servers:
- url: https://api.example.com/users/v2
description: User management production server.
paths:
/users:
get:
summary: Retrieve all users
operationId: getAllUsers
parameters:
- name: limit
in: query
description: Maximum number of users to return.
required: false
schema:
type: integer
format: int32
minimum: 1
maximum: 100
- name: offset
in: query
description: Number of users to skip for pagination.
required: false
schema:
type: integer
format: int32
minimum: 0
responses:
'200':
description: A list of users successfully retrieved.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
post:
summary: Create a new user
operationId: createUser
requestBody:
required: true
description: User data to be created.
content:
application/json:
schema:
$ref: '#/components/schemas/UserInput'
responses:
'201':
description: User successfully created.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
description: Invalid user data provided for creation.
/users/{userId}:
get:
summary: Retrieve a user by ID
operationId: getUserById
parameters:
- name: userId
in: path
required: true
description: Unique identifier of the user to retrieve.
schema:
type: string
format: uuid
responses:
'200':
description: User details successfully retrieved.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'404':
description: User not found with the given ID.
components:
schemas:
User:
type: object
required:
- id
- username
- email
properties:
id:
type: string
format: uuid
description: Unique user identifier.
username:
type: string
description: User's chosen username.
email:
type: string
format: email
description: User's email address.
firstName:
type: string
nullable: true
description: User's first name.
lastName:
type: string
nullable: true
description: User's last name.
createdAt:
type: string
format: date-time
description: Timestamp of user creation.
UserInput:
type: object
required:
- username
- email
- password
properties:
username:
type: string
description: User's chosen username.
email:
type: string
format: email
description: User's email address.
password:
type: string
format: password
description: User's password (should be hashed in real systems).
firstName:
type: string
nullable: true
description: User's first name.
lastName:
type: string
nullable: true
description: User's last name.
