🎯 Recommended Samples
Balanced sample collections from various categories for you to explore
OpenAPI/Swagger Samples
OpenAPI/Swagger specification examples for REST API documentation and contract definition
💻 Basic OpenAPI 3.0 Pet Store API yaml
🟢 simple
Simple OpenAPI 3.0 specification for a pet store management system
🏷️ openapi, petstore, rest, api
openapi: 3.0.0
info:
title: Pet Store API
description: A simple pet store management API
version: 1.0.0
contact:
name: API Support
email: [email protected]
license:
name: MIT
url: https://opensource.org/licenses/MIT
servers:
- url: https://api.petstore.com/v1
description: Production server
- url: https://staging-api.petstore.com/v1
description: Staging server
paths:
/pets:
get:
summary: List all pets
description: Returns a list of all pets in the store
parameters:
- name: limit
in: query
description: Maximum number of pets to return
required: false
schema:
type: integer
default: 20
minimum: 1
maximum: 100
- name: status
in: query
description: Filter by pet status
required: false
schema:
type: string
enum: [available, pending, sold]
responses:
'200':
description: A list of pets
content:
application/json:
schema:
type: object
properties:
pets:
type: array
items:
$ref: '#/components/schemas/Pet'
total:
type: integer
example: 42
'400':
$ref: '#/components/responses/BadRequest'
'500':
$ref: '#/components/responses/InternalServerError'
post:
summary: Add a new pet to the store
description: Creates a new pet in the store
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NewPet'
responses:
'201':
description: Pet created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
'400':
$ref: '#/components/responses/BadRequest'
'500':
$ref: '#/components/responses/InternalServerError'
/pets/{petId}:
get:
summary: Get pet by ID
description: Returns a single pet by its ID
parameters:
- name: petId
in: path
required: true
description: ID of the pet to retrieve
schema:
type: integer
format: int64
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
put:
summary: Update an existing pet
description: Updates pet information
parameters:
- name: petId
in: path
required: true
description: ID of the pet to update
schema:
type: integer
format: int64
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NewPet'
responses:
'200':
description: Pet updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
'404':
$ref: '#/components/responses/NotFound'
'400':
$ref: '#/components/responses/BadRequest'
delete:
summary: Delete a pet
description: Deletes a pet from the store
parameters:
- name: petId
in: path
required: true
description: ID of the pet to delete
schema:
type: integer
format: int64
responses:
'204':
description: Pet deleted successfully
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
components:
schemas:
Pet:
type: object
required:
- id
- name
- status
properties:
id:
type: integer
format: int64
example: 123
readOnly: true
name:
type: string
example: "Buddy"
minLength: 1
maxLength: 100
category:
$ref: '#/components/schemas/Category'
status:
type: string
enum: [available, pending, sold]
example: "available"
tags:
type: array
items:
$ref: '#/components/schemas/Tag'
photoUrls:
type: array
items:
type: string
format: uri
example: ["https://example.com/photos/123.jpg"]
NewPet:
type: object
required:
- name
- status
properties:
name:
type: string
example: "Buddy"
minLength: 1
maxLength: 100
category:
$ref: '#/components/schemas/Category'
status:
type: string
enum: [available, pending, sold]
example: "available"
tags:
type: array
items:
$ref: '#/components/schemas/Tag'
photoUrls:
type: array
items:
type: string
format: uri
Category:
type: object
properties:
id:
type: integer
format: int64
example: 1
name:
type: string
example: "Dogs"
maxLength: 50
Tag:
type: object
properties:
id:
type: integer
format: int64
example: 1
name:
type: string
example: "friendly"
maxLength: 50
Error:
type: object
required:
- code
- message
properties:
code:
type: integer
format: int32
message:
type: string
example: "Validation failed"
responses:
BadRequest:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
InternalServerError:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: API key for authentication
security:
- ApiKeyAuth: []💻 User Management API with Authentication yaml
🟡 intermediate
Complete user management API with authentication, authorization, and role-based access control
🏷️ openapi, authentication, user-management, jwt, roles
openapi: 3.0.1
info:
title: User Management API
description: API for managing users, roles, and permissions
version: 2.1.0
contact:
name: Developer Team
email: [email protected]
url: https://company.com/contact
termsOfService: https://company.com/terms
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://api.company.com/v2
description: Production server
- url: https://staging-api.company.com/v2
description: Staging server
- url: https://dev-api.company.com/v2
description: Development server
tags:
- name: users
description: Operations about users
- name: auth
description: Authentication operations
- name: roles
description: Role management operations
paths:
/auth/login:
post:
tags:
- auth
summary: User login
description: Authenticates a user and returns access tokens
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LoginRequest'
examples:
user_login:
summary: User login
value:
email: "[email protected]"
password: "securePassword123"
admin_login:
summary: Admin login
value:
email: "[email protected]"
password: "adminPassword123"
responses:
'200':
description: Login successful
content:
application/json:
schema:
$ref: '#/components/schemas/LoginResponse'
examples:
user_response:
summary: User token response
value:
accessToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
refreshToken: "def50200f8b75b3a85b78e2686e6df8..."
expiresIn: 3600
tokenType: "Bearer"
user:
id: 123
email: "[email protected]"
roles: ["user"]
'401':
$ref: '#/components/responses/Unauthorized'
'400':
$ref: '#/components/responses/ValidationError'
/auth/refresh:
post:
tags:
- auth
summary: Refresh access token
description: Uses refresh token to generate new access token
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RefreshTokenRequest'
responses:
'200':
description: Token refreshed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/TokenResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/users:
get:
tags:
- users
summary: List users
description: Returns a paginated list of users
security:
- bearerAuth: []
parameters:
- name: page
in: query
description: Page number
required: false
schema:
type: integer
minimum: 1
default: 1
- name: limit
in: query
description: Number of users per page
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 20
- name: search
in: query
description: Search term for users
required: false
schema:
type: string
minLength: 1
maxLength: 100
- name: role
in: query
description: Filter by role
required: false
schema:
type: string
enum: [user, admin, moderator]
- name: status
in: query
description: Filter by status
required: false
schema:
type: string
enum: [active, inactive, suspended]
responses:
'200':
description: Users retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/UserListResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
post:
tags:
- users
summary: Create user
description: Creates a new user account
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUserRequest'
responses:
'201':
description: User created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/UserResponse'
'400':
$ref: '#/components/responses/ValidationError'
'401':
$ref: '#/components/responses/Unauthorized'
'409':
$ref: '#/components/responses/Conflict'
/users/{userId}:
get:
tags:
- users
summary: Get user by ID
description: Returns detailed information about a specific user
security:
- bearerAuth: []
parameters:
- name: userId
in: path
required: true
description: User ID
schema:
type: integer
format: int64
responses:
'200':
description: User retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/UserResponse'
'404':
$ref: '#/components/responses/NotFound'
'401':
$ref: '#/components/responses/Unauthorized'
put:
tags:
- users
summary: Update user
description: Updates user information
security:
- bearerAuth: []
parameters:
- name: userId
in: path
required: true
description: User ID
schema:
type: integer
format: int64
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateUserRequest'
responses:
'200':
description: User updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/UserResponse'
'404':
$ref: '#/components/responses/NotFound'
'400':
$ref: '#/components/responses/ValidationError'
'401':
$ref: '#/components/responses/Unauthorized'
delete:
tags:
- users
summary: Delete user
description: Deletes a user account
security:
- bearerAuth: []
parameters:
- name: userId
in: path
required: true
description: User ID
schema:
type: integer
format: int64
responses:
'204':
description: User deleted successfully
'404':
$ref: '#/components/responses/NotFound'
'401':
$ref: '#/components/responses/Unauthorized'
/users/{userId}/roles:
get:
tags:
- users
summary: Get user roles
description: Returns all roles assigned to a user
security:
- bearerAuth: []
parameters:
- name: userId
in: path
required: true
description: User ID
schema:
type: integer
format: int64
responses:
'200':
description: User roles retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/UserRolesResponse'
components:
schemas:
User:
type: object
required:
- id
- email
- firstName
- lastName
- status
- createdAt
properties:
id:
type: integer
format: int64
example: 123
readOnly: true
email:
type: string
format: email
example: "[email protected]"
maxLength: 255
firstName:
type: string
example: "John"
minLength: 1
maxLength: 100
lastName:
type: string
example: "Doe"
minLength: 1
maxLength: 100
avatar:
type: string
format: uri
example: "https://example.com/avatars/123.jpg"
nullable: true
status:
type: string
enum: [active, inactive, suspended]
example: "active"
roles:
type: array
items:
$ref: '#/components/schemas/Role'
example:
- id: 1
name: "user"
lastLoginAt:
type: string
format: date-time
nullable: true
example: "2025-11-30T10:30:00Z"
createdAt:
type: string
format: date-time
readOnly: true
example: "2025-01-15T09:00:00Z"
updatedAt:
type: string
format: date-time
readOnly: true
example: "2025-11-29T14:20:00Z"
CreateUserRequest:
type: object
required:
- email
- firstName
- lastName
- password
properties:
email:
type: string
format: email
example: "[email protected]"
maxLength: 255
firstName:
type: string
example: "Jane"
minLength: 1
maxLength: 100
lastName:
type: string
example: "Smith"
minLength: 1
maxLength: 100
password:
type: string
format: password
example: "securePassword123"
minLength: 8
maxLength: 128
roleIds:
type: array
items:
type: integer
format: int64
example: [1]
default: [1]
UpdateUserRequest:
type: object
properties:
firstName:
type: string
example: "Jane"
minLength: 1
maxLength: 100
lastName:
type: string
example: "Smith"
minLength: 1
maxLength: 100
avatar:
type: string
format: uri
example: "https://example.com/avatars/456.jpg"
nullable: true
status:
type: string
enum: [active, inactive, suspended]
example: "active"
LoginRequest:
type: object
required:
- email
- password
properties:
email:
type: string
format: email
example: "[email protected]"
password:
type: string
format: password
example: "securePassword123"
LoginResponse:
type: object
required:
- accessToken
- refreshToken
- expiresIn
- tokenType
- user
properties:
accessToken:
type: string
example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
refreshToken:
type: string
example: "def50200f8b75b3a85b78e2686e6df8..."
expiresIn:
type: integer
example: 3600
tokenType:
type: string
example: "Bearer"
user:
$ref: '#/components/schemas/User'
TokenResponse:
type: object
required:
- accessToken
- expiresIn
- tokenType
properties:
accessToken:
type: string
example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
expiresIn:
type: integer
example: 3600
tokenType:
type: string
example: "Bearer"
RefreshTokenRequest:
type: object
required:
- refreshToken
properties:
refreshToken:
type: string
example: "def50200f8b75b3a85b78e2686e6df8..."
UserListResponse:
type: object
required:
- users
- pagination
properties:
users:
type: array
items:
$ref: '#/components/schemas/User'
pagination:
$ref: '#/components/schemas/Pagination'
UserResponse:
type: object
required:
- user
properties:
user:
$ref: '#/components/schemas/User'
UserRolesResponse:
type: object
required:
- userId
- roles
properties:
userId:
type: integer
format: int64
example: 123
roles:
type: array
items:
$ref: '#/components/schemas/Role'
Role:
type: object
required:
- id
- name
properties:
id:
type: integer
format: int64
example: 1
name:
type: string
example: "user"
description:
type: string
example: "Regular user role"
nullable: true
permissions:
type: array
items:
type: string
example: ["read:profile", "write:profile"]
Pagination:
type: object
required:
- page
- limit
- total
- totalPages
properties:
page:
type: integer
example: 1
limit:
type: integer
example: 20
total:
type: integer
example: 125
totalPages:
type: integer
example: 7
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
example: "VALIDATION_ERROR"
message:
type: string
example: "Validation failed"
details:
type: array
items:
type: object
properties:
field:
type: string
example: "email"
message:
type: string
example: "Email is required"
responses:
BadRequest:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Forbidden:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Conflict:
description: Resource conflict
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
ValidationError:
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: JWT access token
security:
- bearerAuth: []💻 E-commerce API with Advanced Features yaml
🔴 complex
Complete e-commerce API with products, orders, payments, and inventory management
🏷️ openapi, ecommerce, products, orders, payments, inventory
openapi: 3.0.3
info:
title: E-commerce Platform API
description: Comprehensive e-commerce API with product catalog, shopping cart, orders, payments, and inventory management
version: 3.2.0
contact:
name: API Team
email: [email protected]
url: https://ecommerce.com/api-docs
termsOfService: https://ecommerce.com/terms
license:
name: MIT
url: https://opensource.org/licenses/MIT
servers:
- url: https://api.ecommerce.com/v3
description: Production server
- url: https://staging-api.ecommerce.com/v3
description: Staging server
- url: https://sandbox-api.ecommerce.com/v3
description: Sandbox environment
tags:
- name: products
description: Product catalog operations
- name: cart
description: Shopping cart operations
- name: orders
description: Order management operations
- name: payments
description: Payment processing operations
- name: inventory
description: Inventory management operations
paths:
/products:
get:
tags:
- products
summary: List products
description: Returns a paginated list of products with filtering and sorting options
security:
- apiKeyAuth: []
parameters:
- name: page
in: query
schema:
type: integer
minimum: 1
default: 1
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 20
- name: category
in: query
schema:
type: string
- name: minPrice
in: query
schema:
type: number
format: float
minimum: 0
- name: maxPrice
in: query
schema:
type: number
format: float
minimum: 0
- name: search
in: query
schema:
type: string
- name: sortBy
in: query
schema:
type: string
enum: [price, name, created_at, rating]
default: created_at
- name: sortOrder
in: query
schema:
type: string
enum: [asc, desc]
default: desc
- name: inStock
in: query
schema:
type: boolean
- name: tags
in: query
style: form
explode: false
schema:
type: array
items:
type: string
responses:
'200':
description: Products retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ProductListResponse'
examples:
electronics_filter:
summary: Products filtered by electronics category
value:
products:
- id: 1
name: "Smartphone X"
price: 699.99
category: "Electronics"
inStock: true
rating: 4.5
images:
- "https://example.com/products/1/image1.jpg"
pagination:
page: 1
limit: 20
total: 45
totalPages: 3
post:
tags:
- products
summary: Create product
description: Creates a new product in the catalog
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateProductRequest'
multipart/form-data:
schema:
$ref: '#/components/schemas/CreateProductFormData'
responses:
'201':
description: Product created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ProductResponse'
/products/{productId}:
get:
tags:
- products
summary: Get product by ID
description: Returns detailed information about a specific product
security:
- apiKeyAuth: []
parameters:
- name: productId
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Product retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ProductDetailResponse'
'404':
$ref: '#/components/responses/NotFound'
put:
tags:
- products
summary: Update product
description: Updates product information
security:
- bearerAuth: []
parameters:
- name: productId
in: path
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateProductRequest'
responses:
'200':
description: Product updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ProductResponse'
delete:
tags:
- products
summary: Delete product
description: Removes a product from the catalog
security:
- bearerAuth: []
parameters:
- name: productId
in: path
required: true
schema:
type: string
format: uuid
responses:
'204':
description: Product deleted successfully
/cart:
get:
tags:
- cart
summary: Get shopping cart
description: Returns the current user's shopping cart
security:
- bearerAuth: []
responses:
'200':
description: Shopping cart retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CartResponse'
post:
tags:
- cart
summary: Add item to cart
description: Adds a product to the shopping cart
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AddToCartRequest'
responses:
'201':
description: Item added to cart successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CartItemResponse'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
put:
tags:
- cart
summary: Update cart item quantity
description: Updates the quantity of an item in the cart
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateCartItemRequest'
responses:
'200':
description: Cart item updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CartItemResponse'
delete:
tags:
- cart
summary: Remove item from cart
description: Removes an item from the shopping cart
security:
- bearerAuth: []
parameters:
- name: itemId
in: query
required: true
schema:
type: string
format: uuid
responses:
'204':
description: Item removed from cart
/orders:
get:
tags:
- orders
summary: List orders
description: Returns a paginated list of user orders
security:
- bearerAuth: []
parameters:
- name: page
in: query
schema:
type: integer
minimum: 1
default: 1
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 50
default: 20
- name: status
in: query
schema:
type: string
enum: [pending, processing, shipped, delivered, cancelled]
- name: dateFrom
in: query
schema:
type: string
format: date
- name: dateTo
in: query
schema:
type: string
format: date
responses:
'200':
description: Orders retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/OrderListResponse'
post:
tags:
- orders
summary: Create order
description: Creates a new order from the shopping cart
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateOrderRequest'
responses:
'201':
description: Order created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/OrderResponse'
/orders/{orderId}:
get:
tags:
- orders
summary: Get order by ID
description: Returns detailed information about a specific order
security:
- bearerAuth: []
parameters:
- name: orderId
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Order retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/OrderDetailResponse'
/payments:
post:
tags:
- payments
summary: Process payment
description: Processes payment for an order
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentRequest'
responses:
'200':
description: Payment processed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentResponse'
'400':
$ref: '#/components/responses/PaymentError'
'402':
$ref: '#/components/responses/PaymentFailed'
components:
schemas:
Product:
type: object
required:
- id
- name
- price
- category
- inStock
- createdAt
properties:
id:
type: string
format: uuid
example: "550e8400-e29b-41d4-a716-446655440000"
readOnly: true
name:
type: string
example: "Wireless Headphones"
maxLength: 200
description:
type: string
example: "Premium noise-cancelling wireless headphones"
maxLength: 1000
price:
type: number
format: float
example: 199.99
minimum: 0
originalPrice:
type: number
format: float
example: 299.99
nullable: true
currency:
type: string
example: "USD"
default: "USD"
category:
type: string
example: "Electronics"
subcategory:
type: string
example: "Audio"
nullable: true
brand:
type: string
example: "TechBrand"
maxLength: 100
sku:
type: string
example: "WH-NC-001"
maxLength: 50
images:
type: array
items:
type: string
format: uri
maxItems: 10
tags:
type: array
items:
type: string
maxItems: 20
inStock:
type: boolean
example: true
inventory:
type: integer
example: 150
minimum: 0
weight:
type: number
format: float
example: 0.5
nullable: true
dimensions:
$ref: '#/components/schemas/Dimensions'
rating:
type: number
format: float
example: 4.5
minimum: 0
maximum: 5
reviewCount:
type: integer
example: 328
minimum: 0
createdAt:
type: string
format: date-time
readOnly: true
updatedAt:
type: string
format: date-time
readOnly: true
Dimensions:
type: object
properties:
length:
type: number
format: float
example: 7.5
width:
type: number
format: float
example: 6.2
height:
type: number
format: float
example: 3.1
unit:
type: string
example: "inches"
default: "inches"
CreateProductRequest:
type: object
required:
- name
- price
- category
- inventory
properties:
name:
type: string
example: "Wireless Headphones"
maxLength: 200
description:
type: string
example: "Premium noise-cancelling wireless headphones"
maxLength: 1000
price:
type: number
format: float
example: 199.99
minimum: 0
originalPrice:
type: number
format: float
example: 299.99
nullable: true
category:
type: string
example: "Electronics"
subcategory:
type: string
example: "Audio"
nullable: true
brand:
type: string
example: "TechBrand"
maxLength: 100
sku:
type: string
example: "WH-NC-001"
maxLength: 50
tags:
type: array
items:
type: string
maxItems: 20
inventory:
type: integer
example: 150
minimum: 0
weight:
type: number
format: float
example: 0.5
nullable: true
dimensions:
$ref: '#/components/schemas/Dimensions'
ProductListResponse:
type: object
required:
- products
- pagination
properties:
products:
type: array
items:
$ref: '#/components/schemas/Product'
pagination:
$ref: '#/components/schemas/Pagination'
filters:
type: object
properties:
applied:
type: array
items:
type: string
available:
type: array
items:
type: string
ProductDetailResponse:
type: object
required:
- product
properties:
product:
$ref: '#/components/schemas/Product'
relatedProducts:
type: array
items:
$ref: '#/components/schemas/Product'
reviews:
type: array
items:
$ref: '#/components/schemas/Review'
Cart:
type: object
required:
- id
- items
- subtotal
- tax
- total
- currency
properties:
id:
type: string
format: uuid
example: "550e8400-e29b-41d4-a716-446655440000"
readOnly: true
items:
type: array
items:
$ref: '#/components/schemas/CartItem'
subtotal:
type: number
format: float
example: 89.97
tax:
type: number
format: float
example: 7.20
shipping:
type: number
format: float
example: 5.99
discount:
type: number
format: float
example: 10.00
total:
type: number
format: float
example: 93.16
currency:
type: string
example: "USD"
createdAt:
type: string
format: date-time
readOnly: true
updatedAt:
type: string
format: date-time
readOnly: true
CartItem:
type: object
required:
- id
- product
- quantity
- unitPrice
- totalPrice
properties:
id:
type: string
format: uuid
example: "550e8400-e29b-41d4-a716-446655440000"
readOnly: true
product:
$ref: '#/components/schemas/Product'
quantity:
type: integer
example: 2
minimum: 1
maximum: 99
unitPrice:
type: number
format: float
example: 29.99
readOnly: true
totalPrice:
type: number
format: float
example: 59.98
readOnly: true
addedAt:
type: string
format: date-time
readOnly: true
Order:
type: object
required:
- id
- items
- status
- total
- createdAt
properties:
id:
type: string
format: uuid
example: "550e8400-e29b-41d4-a716-446655440000"
readOnly: true
items:
type: array
items:
$ref: '#/components/schemas/OrderItem'
status:
type: string
enum: [pending, processing, shipped, delivered, cancelled]
example: "processing"
subtotal:
type: number
format: float
example: 89.97
tax:
type: number
format: float
example: 7.20
shipping:
type: number
format: float
example: 5.99
discount:
type: number
format: float
example: 10.00
total:
type: number
format: float
example: 93.16
currency:
type: string
example: "USD"
shippingAddress:
$ref: '#/components/schemas/Address'
billingAddress:
$ref: '#/components/schemas/Address'
trackingNumber:
type: string
example: "1Z9999W99999999999"
nullable: true
estimatedDelivery:
type: string
format: date
example: "2025-12-05"
nullable: true
createdAt:
type: string
format: date-time
readOnly: true
updatedAt:
type: string
format: date-time
readOnly: true
OrderItem:
type: object
required:
- product
- quantity
- unitPrice
- totalPrice
properties:
product:
$ref: '#/components/schemas/Product'
quantity:
type: integer
example: 2
minimum: 1
unitPrice:
type: number
format: float
example: 29.99
readOnly: true
totalPrice:
type: number
format: float
example: 59.98
readOnly: true
Address:
type: object
required:
- street
- city
- state
- postalCode
- country
properties:
street:
type: string
example: "123 Main St"
maxLength: 200
street2:
type: string
example: "Apt 4B"
maxLength: 200
nullable: true
city:
type: string
example: "New York"
maxLength: 100
state:
type: string
example: "NY"
maxLength: 50
postalCode:
type: string
example: "10001"
maxLength: 20
country:
type: string
example: "USA"
maxLength: 50
PaymentRequest:
type: object
required:
- orderId
- paymentMethod
- amount
properties:
orderId:
type: string
format: uuid
example: "550e8400-e29b-41d4-a716-446655440000"
paymentMethod:
type: string
enum: [credit_card, debit_card, paypal, bank_transfer]
example: "credit_card"
paymentDetails:
oneOf:
- $ref: '#/components/schemas/CreditCardPayment'
- $ref: '#/components/schemas/PayPalPayment'
- $ref: '#/components/schemas/BankTransferPayment'
amount:
type: number
format: float
example: 93.16
currency:
type: string
example: "USD"
savePaymentMethod:
type: boolean
example: false
PaymentResponse:
type: object
required:
- paymentId
- status
- amount
- currency
properties:
paymentId:
type: string
format: uuid
example: "550e8400-e29b-41d4-a716-446655440000"
status:
type: string
enum: [pending, processing, completed, failed, cancelled]
example: "completed"
transactionId:
type: string
example: "txn_1234567890"
nullable: true
amount:
type: number
format: float
example: 93.16
currency:
type: string
example: "USD"
processedAt:
type: string
format: date-time
nullable: true
receiptUrl:
type: string
format: uri
example: "https://example.com/receipts/txn_1234567890"
nullable: true
Pagination:
type: object
required:
- page
- limit
- total
- totalPages
properties:
page:
type: integer
example: 1
limit:
type: integer
example: 20
total:
type: integer
example: 125
totalPages:
type: integer
example: 7
hasNext:
type: boolean
example: true
hasPrev:
type: boolean
example: false
Review:
type: object
required:
- id
- rating
- comment
- reviewer
- createdAt
properties:
id:
type: string
format: uuid
example: "550e8400-e29b-41d4-a716-446655440000"
rating:
type: integer
example: 4
minimum: 1
maximum: 5
comment:
type: string
example: "Great product, works as expected!"
maxLength: 1000
reviewer:
type: object
properties:
name:
type: string
example: "John D."
avatar:
type: string
format: uri
example: "https://example.com/avatars/john.jpg"
verified:
type: boolean
example: true
helpful:
type: integer
example: 12
createdAt:
type: string
format: date-time
readOnly: true
responses:
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
BadRequest:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
PaymentFailed:
description: Payment processing failed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
PaymentError:
description: Payment error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
example: "PAYMENT_DECLINED"
message:
type: string
example: "Payment was declined by the processor"
details:
type: object
additionalProperties: true
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: API key for public endpoints
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: JWT access token for authenticated endpoints
security:
- apiKeyAuth: []
- bearerAuth: []