Exemples OpenAPI/Swagger
Exemples complets de documentation API utilisant OpenAPI 3.0 et les spécifications Swagger pour les services RESTful
Key Facts
- Category
- API Documentation
- Items
- 3
- Format Families
- json, yaml
Sample Overview
Exemples complets de documentation API utilisant OpenAPI 3.0 et les spécifications Swagger pour les services RESTful This sample set belongs to API Documentation and can be used to test related workflows inside Elysia Tools.
📋 API REST de Base OpenAPI 3.0
🟢 simple
⭐⭐⭐
Spécification OpenAPI 3.0 complète pour une API REST de gestion d'utilisateurs avec opérations CRUD
⏱️ 20 min
🏷️ openapi, api-documentation, rest
Prerequisites:
REST API concepts, JSON/YAML
{
"openapi": "3.0.3",
"info": {
"title": "User Management API",
"description": "A simple REST API for managing users with CRUD operations",
"version": "1.0.0",
"contact": {
"name": "API Support",
"email": "[email protected]",
"url": "https://example.com/support"
},
"license": {
"name": "MIT",
"url": "https://opensource.org/licenses/MIT"
}
},
"servers": [
{
"url": "https://api.example.com/v1",
"description": "Production server"
},
{
"url": "https://staging-api.example.com/v1",
"description": "Staging server"
},
{
"url": "http://localhost:3000/v1",
"description": "Development server"
}
],
"paths": {
"/users": {
"get": {
"summary": "Get all users",
"description": "Retrieve a paginated list of users",
"tags": ["Users"],
"parameters": [
{
"name": "page",
"in": "query",
"description": "Page number for pagination",
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
}
},
{
"name": "limit",
"in": "query",
"description": "Number of items per page",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 10
}
},
{
"name": "search",
"in": "query",
"description": "Search term to filter users",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserListResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
},
"post": {
"summary": "Create a new user",
"description": "Create a new user with the provided information",
"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/UserResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"409": {
"$ref": "#/components/responses/Conflict"
}
}
}
},
"/users/{userId}": {
"get": {
"summary": "Get user by ID",
"description": "Retrieve a specific user by their ID",
"tags": ["Users"],
"parameters": [
{
"name": "userId",
"in": "path",
"required": true,
"description": "Unique identifier of the user",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserResponse"
}
}
}
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
},
"put": {
"summary": "Update user",
"description": "Update an existing user's information",
"tags": ["Users"],
"parameters": [
{
"name": "userId",
"in": "path",
"required": true,
"description": "Unique identifier of the user",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"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"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"delete": {
"summary": "Delete user",
"description": "Delete a user by their ID",
"tags": ["Users"],
"parameters": [
{
"name": "userId",
"in": "path",
"required": true,
"description": "Unique identifier of the user",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "User deleted successfully"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
}
},
"components": {
"schemas": {
"User": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of the user"
},
"username": {
"type": "string",
"minLength": 3,
"maxLength": 50,
"pattern": "^[a-zA-Z0-9_]+$",
"description": "Unique username"
},
"email": {
"type": "string",
"format": "email",
"description": "User's email address"
},
"firstName": {
"type": "string",
"minLength": 1,
"maxLength": 50,
"description": "User's first name"
},
"lastName": {
"type": "string",
"minLength": 1,
"maxLength": 50,
"description": "User's last name"
},
"role": {
"$ref": "#/components/schemas/UserRole"
},
"isActive": {
"type": "boolean",
"description": "Whether the user account is active"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the user was created"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the user was last updated"
}
},
"required": ["id", "username", "email", "firstName", "lastName", "role", "isActive", "createdAt", "updatedAt"],
"example": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"username": "johndoe",
"email": "[email protected]",
"firstName": "John",
"lastName": "Doe",
"role": "user",
"isActive": true,
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z"
}
},
"UserRole": {
"type": "string",
"enum": ["admin", "moderator", "user"],
"description": "User role in the system"
},
"CreateUserRequest": {
"type": "object",
"properties": {
"username": {
"type": "string",
"minLength": 3,
"maxLength": 50,
"pattern": "^[a-zA-Z0-9_]+$",
"description": "Unique username"
},
"email": {
"type": "string",
"format": "email",
"description": "User's email address"
},
"password": {
"type": "string",
"minLength": 8,
"description": "User's password (minimum 8 characters)"
},
"firstName": {
"type": "string",
"minLength": 1,
"maxLength": 50,
"description": "User's first name"
},
"lastName": {
"type": "string",
"minLength": 1,
"maxLength": 50,
"description": "User's last name"
},
"role": {
"$ref": "#/components/schemas/UserRole"
}
},
"required": ["username", "email", "password", "firstName", "lastName"]
},
"UpdateUserRequest": {
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email",
"description": "User's email address"
},
"firstName": {
"type": "string",
"minLength": 1,
"maxLength": 50,
"description": "User's first name"
},
"lastName": {
"type": "string",
"minLength": 1,
"maxLength": 50,
"description": "User's last name"
},
"role": {
"$ref": "#/components/schemas/UserRole"
},
"isActive": {
"type": "boolean",
"description": "Whether the user account is active"
}
}
},
"UserResponse": {
"allOf": [
{
"$ref": "#/components/schemas/User"
}
]
},
"UserListResponse": {
"type": "object",
"properties": {
"users": {
"type": "array",
"items": {
"$ref": "#/components/schemas/User"
}
},
"pagination": {
"$ref": "#/components/schemas/Pagination"
}
}
},
"Pagination": {
"type": "object",
"properties": {
"page": {
"type": "integer",
"minimum": 1,
"description": "Current page number"
},
"limit": {
"type": "integer",
"minimum": 1,
"description": "Number of items per page"
},
"totalItems": {
"type": "integer",
"minimum": 0,
"description": "Total number of items"
},
"totalPages": {
"type": "integer",
"minimum": 0,
"description": "Total number of pages"
}
}
},
"ErrorResponse": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error message"
},
"code": {
"type": "string",
"description": "Error code"
},
"details": {
"type": "object",
"description": "Additional error details"
}
},
"required": ["error", "code"]
}
},
"responses": {
"BadRequest": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"error": "Invalid request data",
"code": "BAD_REQUEST",
"details": {
"field": "email",
"message": "Invalid email format"
}
}
}
}
},
"Unauthorized": {
"description": "Unauthorized access",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"error": "Authentication required",
"code": "UNAUTHORIZED"
}
}
}
},
"NotFound": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"error": "User not found",
"code": "NOT_FOUND"
}
}
}
},
"Conflict": {
"description": "Resource conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"error": "Username already exists",
"code": "CONFLICT"
}
}
}
}
},
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT",
"description": "JWT token for authentication"
},
"apiKey": {
"type": "apiKey",
"in": "header",
"name": "X-API-Key",
"description": "API key for authentication"
}
}
},
"security": [
{
"bearerAuth": []
},
{
"apiKey": []
}
],
"tags": [
{
"name": "Users",
"description": "User management operations"
}
]
}💻 API E-commerce OpenAPI 3.0
🟡 intermediate
⭐⭐⭐⭐
Spécification API e-commerce complète avec gestion des produits, commandes, paiements et inventaire
⏱️ 30 min
🏷️ openapi, ecommerce, api-design
Prerequisites:
OpenAPI basics, e-commerce concepts, YAML
openapi: 3.0.3
info:
title: E-commerce Platform API
description: A complete e-commerce API for managing products, orders, payments, and inventory
version: 2.1.0
contact:
name: API Team
email: [email protected]
url: https://ecommerce.com/api-support
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.ecommerce.com/v2
description: Production server
- url: https://staging-api.ecommerce.com/v2
description: Staging server
- url: http://localhost:8080/v2
description: Development server
paths:
/products:
get:
summary: List products
description: Retrieve a paginated list of products with filtering and sorting options
tags:
- Products
parameters:
- name: page
in: query
description: Page number for pagination
schema:
type: integer
minimum: 1
default: 1
- name: limit
in: query
description: Number of products per page
schema:
type: integer
minimum: 1
maximum: 100
default: 20
- name: category
in: query
description: Filter by category ID
schema:
type: string
format: uuid
- name: minPrice
in: query
description: Minimum price filter
schema:
type: number
minimum: 0
- name: maxPrice
in: query
description: Maximum price filter
schema:
type: number
minimum: 0
- name: sortBy
in: query
description: Sort field
schema:
type: string
enum: [price, name, createdAt, rating, sales]
default: createdAt
- name: sortOrder
in: query
description: Sort order
schema:
type: string
enum: [asc, desc]
default: desc
- name: search
in: query
description: Search term
schema:
type: string
responses:
'200':
description: Products retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ProductListResponse'
'400':
$ref: '#/components/responses/BadRequest'
post:
summary: Create product
description: Create a new product
tags:
- Products
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateProductRequest'
responses:
'201':
description: Product created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ProductResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/products/{productId}:
get:
summary: Get product details
description: Retrieve detailed information about a specific product
tags:
- Products
parameters:
- name: productId
in: path
required: true
description: Product ID
schema:
type: string
format: uuid
responses:
'200':
description: Product retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ProductDetailResponse'
'404':
$ref: '#/components/responses/NotFound'
/orders:
get:
summary: List orders
description: Retrieve user's orders with pagination and filtering
tags:
- 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: 10
- name: status
in: query
description: Filter by order status
schema:
$ref: '#/components/schemas/OrderStatus'
- name: startDate
in: query
description: Filter orders from this date
schema:
type: string
format: date
- name: endDate
in: query
description: Filter orders until this date
schema:
type: string
format: date
responses:
'200':
description: Orders retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/OrderListResponse'
'401':
$ref: '#/components/responses/Unauthorized'
post:
summary: Create order
description: Create a new order from shopping cart
tags:
- Orders
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'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/orders/{orderId}:
get:
summary: Get order details
description: Retrieve detailed information about a specific order
tags:
- Orders
security:
- bearerAuth: []
parameters:
- name: orderId
in: path
required: true
description: Order ID
schema:
type: string
format: uuid
responses:
'200':
description: Order retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/OrderDetailResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/payments:
post:
summary: Process payment
description: Process payment for an order
tags:
- Payments
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProcessPaymentRequest'
responses:
'200':
description: Payment processed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
description: Payment failed
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentErrorResponse'
/inventory/{productId}:
get:
summary: Get product inventory
description: Get current inventory levels for a product
tags:
- Inventory
parameters:
- name: productId
in: path
required: true
description: Product ID
schema:
type: string
format: uuid
responses:
'200':
description: Inventory retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/InventoryResponse'
components:
schemas:
Product:
type: object
properties:
id:
type: string
format: uuid
description: Product unique identifier
name:
type: string
maxLength: 200
description: Product name
description:
type: string
maxLength: 2000
description: Product description
price:
type: number
format: decimal
minimum: 0
description: Product price
originalPrice:
type: number
format: decimal
minimum: 0
description: Original price (if discounted)
sku:
type: string
maxLength: 50
description: Stock keeping unit
category:
$ref: '#/components/schemas/Category'
images:
type: array
items:
$ref: '#/components/schemas/ProductImage'
attributes:
type: array
items:
$ref: '#/components/schemas/ProductAttribute'
rating:
type: number
format: float
minimum: 0
maximum: 5
description: Average customer rating
reviewCount:
type: integer
minimum: 0
description: Number of customer reviews
isActive:
type: boolean
description: Whether the product is active
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
required: [id, name, description, price, sku, category, isActive, createdAt, updatedAt]
Category:
type: object
properties:
id:
type: string
format: uuid
name:
type: string
maxLength: 100
slug:
type: string
maxLength: 100
parentId:
type: string
format: uuid
nullable: true
ProductImage:
type: object
properties:
url:
type: string
format: uri
alt:
type: string
maxLength: 200
isPrimary:
type: boolean
ProductAttribute:
type: object
properties:
name:
type: string
maxLength: 100
value:
type: string
maxLength: 200
CreateProductRequest:
type: object
required: [name, description, price, sku, categoryId]
properties:
name:
type: string
maxLength: 200
description:
type: string
maxLength: 2000
price:
type: number
format: decimal
minimum: 0
originalPrice:
type: number
format: decimal
minimum: 0
sku:
type: string
maxLength: 50
categoryId:
type: string
format: uuid
images:
type: array
items:
type: string
format: uri
attributes:
type: array
items:
type: object
properties:
name:
type: string
maxLength: 100
value:
type: string
maxLength: 200
ProductResponse:
allOf:
- $ref: '#/components/schemas/Product'
- type: object
properties:
inventory:
$ref: '#/components/schemas/InventoryInfo'
ProductDetailResponse:
allOf:
- $ref: '#/components/schemas/ProductResponse'
- type: object
properties:
reviews:
type: array
items:
$ref: '#/components/schemas/ProductReview'
relatedProducts:
type: array
items:
$ref: '#/components/schemas/Product'
ProductReview:
type: object
properties:
id:
type: string
format: uuid
userId:
type: string
format: uuid
username:
type: string
rating:
type: integer
minimum: 1
maximum: 5
comment:
type: string
maxLength: 1000
createdAt:
type: string
format: date-time
InventoryInfo:
type: object
properties:
quantity:
type: integer
minimum: 0
available:
type: integer
minimum: 0
reserved:
type: integer
minimum: 0
lowStockThreshold:
type: integer
minimum: 0
OrderStatus:
type: string
enum: [pending, confirmed, processing, shipped, delivered, cancelled, refunded]
description: Order status
Order:
type: object
properties:
id:
type: string
format: uuid
orderNumber:
type: string
description: Human-readable order number
userId:
type: string
format: uuid
status:
$ref: '#/components/schemas/OrderStatus'
items:
type: array
items:
$ref: '#/components/schemas/OrderItem'
subtotal:
type: number
format: decimal
minimum: 0
tax:
type: number
format: decimal
minimum: 0
shipping:
type: number
format: decimal
minimum: 0
total:
type: number
format: decimal
minimum: 0
currency:
type: string
length: 3
default: USD
shippingAddress:
$ref: '#/components/schemas/Address'
billingAddress:
$ref: '#/components/schemas/Address'
paymentMethod:
type: string
paymentStatus:
type: string
enum: [pending, paid, failed, refunded]
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
OrderItem:
type: object
properties:
productId:
type: string
format: uuid
productSku:
type: string
productName:
type: string
quantity:
type: integer
minimum: 1
unitPrice:
type: number
format: decimal
minimum: 0
totalPrice:
type: number
format: decimal
minimum: 0
Address:
type: object
properties:
street:
type: string
maxLength: 200
city:
type: string
maxLength: 100
state:
type: string
maxLength: 100
zipCode:
type: string
maxLength: 20
country:
type: string
maxLength: 100
CreateOrderRequest:
type: object
required: [items, shippingAddress, paymentMethod]
properties:
items:
type: array
items:
type: object
properties:
productId:
type: string
format: uuid
quantity:
type: integer
minimum: 1
shippingAddress:
$ref: '#/components/schemas/Address'
billingAddress:
$ref: '#/components/schemas/Address'
paymentMethod:
type: string
couponCode:
type: string
PaymentMethod:
type: string
enum: [credit_card, debit_card, paypal, stripe, apple_pay, google_pay]
ProcessPaymentRequest:
type: object
required: [orderId, paymentMethod]
properties:
orderId:
type: string
format: uuid
paymentMethod:
$ref: '#/components/schemas/PaymentMethod'
paymentDetails:
oneOf:
- $ref: '#/components/schemas/CreditCardPayment'
- $ref: '#/components/schemas/PayPalPayment'
CreditCardPayment:
type: object
required: [cardNumber, expiryMonth, expiryYear, cvv, cardholderName]
properties:
cardNumber:
type: string
pattern: '^[0-9]{16}$'
expiryMonth:
type: integer
minimum: 1
maximum: 12
expiryYear:
type: integer
minimum: 2024
cvv:
type: string
pattern: '^[0-9]{3,4}$'
cardholderName:
type: string
maxLength: 100
PayPalPayment:
type: object
required: [paypalEmail]
properties:
paypalEmail:
type: string
format: email
PaymentResponse:
type: object
properties:
paymentId:
type: string
format: uuid
orderId:
type: string
format: uuid
status:
type: string
enum: [success, failed, pending]
amount:
type: number
format: decimal
currency:
type: string
transactionId:
type: string
paymentMethod:
$ref: '#/components/schemas/PaymentMethod'
processedAt:
type: string
format: date-time
ProductListResponse:
type: object
properties:
products:
type: array
items:
$ref: '#/components/schemas/ProductResponse'
pagination:
$ref: '#/components/schemas/Pagination'
filters:
type: object
properties:
categories:
type: array
items:
$ref: '#/components/schemas/Category'
priceRange:
type: object
properties:
min:
type: number
max:
type: number
OrderListResponse:
type: object
properties:
orders:
type: array
items:
$ref: '#/components/schemas/Order'
pagination:
$ref: '#/components/schemas/Pagination'
Pagination:
type: object
properties:
page:
type: integer
minimum: 1
limit:
type: integer
minimum: 1
totalItems:
type: integer
minimum: 0
totalPages:
type: integer
minimum: 0
hasNext:
type: boolean
hasPrev:
type: boolean
ErrorResponse:
type: object
required: [error, code]
properties:
error:
type: string
code:
type: string
message:
type: string
details:
type: object
responses:
BadRequest:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Unauthorized:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Forbidden:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: JWT authentication token
tags:
- name: Products
description: Product management endpoints
- name: Orders
description: Order management endpoints
- name: Payments
description: Payment processing endpoints
- name: Inventory
description: Inventory management endpoints📋 Spécification Webhooks OpenAPI 3.1
🟡 intermediate
⭐⭐⭐
Spécification API webhooks pour les notifications d'événements en temps réel avec sécurité et mécanismes de retry
⏱️ 25 min
🏷️ openapi, webhooks, events, api
Prerequisites:
OpenAPI basics, webhook concepts, event-driven architecture
{
"openapi": "3.1.0",
"info": {
"title": "Webhook Events API",
"description": "API specification for webhook event notifications and management",
"version": "1.2.0",
"contact": {
"name": "Webhook Support",
"email": "[email protected]"
}
},
"servers": [
{
"url": "https://api.example.com/webhooks/v1",
"description": "Production webhook API"
}
],
"paths": {
"/webhooks": {
"get": {
"summary": "List webhooks",
"description": "Retrieve all configured webhooks for the authenticated user",
"tags": ["Webhooks"],
"security": [
{
"bearerAuth": []
}
],
"responses": {
"200": {
"description": "Webhooks retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"webhooks": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Webhook"
}
}
}
}
}
}
}
}
},
"post": {
"summary": "Create webhook",
"description": "Create a new webhook endpoint",
"tags": ["Webhooks"],
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateWebhookRequest"
}
}
}
},
"responses": {
"201": {
"description": "Webhook created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Webhook"
}
}
}
}
}
}
},
"/webhooks/{webhookId}": {
"get": {
"summary": "Get webhook details",
"description": "Retrieve details of a specific webhook",
"tags": ["Webhooks"],
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"name": "webhookId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Webhook details retrieved",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookDetail"
}
}
}
}
}
},
"put": {
"summary": "Update webhook",
"description": "Update an existing webhook configuration",
"tags": ["Webhooks"],
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"name": "webhookId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateWebhookRequest"
}
}
}
},
"responses": {
"200": {
"description": "Webhook updated successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Webhook"
}
}
}
}
}
},
"delete": {
"summary": "Delete webhook",
"description": "Delete a webhook endpoint",
"tags": ["Webhooks"],
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"name": "webhookId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "Webhook deleted successfully"
}
}
}
},
"/webhooks/{webhookId}/test": {
"post": {
"summary": "Test webhook",
"description": "Send a test event to the webhook endpoint",
"tags": ["Webhooks"],
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"name": "webhookId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"eventType": {
"type": "string",
"description": "Type of test event to send",
"enum": ["user.created", "order.completed", "payment.failed"]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Test webhook sent successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookTestResult"
}
}
}
}
}
}
},
"/webhooks/{webhookId}/logs": {
"get": {
"summary": "Get webhook delivery logs",
"description": "Retrieve delivery logs for a specific webhook",
"tags": ["Webhooks"],
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"name": "webhookId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": ["success", "failed", "pending"]
}
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 20
}
}
],
"responses": {
"200": {
"description": "Webhook logs retrieved",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"logs": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WebhookLog"
}
}
}
}
}
}
}
}
}
}
},
"webhooks": {
"user.created": {
"description": "Triggered when a new user account is created",
"post": {
"summary": "User Created Event",
"requestBody": {
"description": "User creation event payload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserCreatedEvent"
}
}
}
},
"responses": {
"200": {
"description": "Webhook processed successfully"
},
"400": {
"description": "Invalid webhook payload or endpoint"
}
}
}
},
"order.completed": {
"description": "Triggered when an order is completed",
"post": {
"summary": "Order Completed Event",
"requestBody": {
"description": "Order completion event payload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrderCompletedEvent"
}
}
}
},
"responses": {
"200": {
"description": "Webhook processed successfully"
}
}
}
},
"payment.failed": {
"description": "Triggered when a payment fails",
"post": {
"summary": "Payment Failed Event",
"requestBody": {
"description": "Payment failure event payload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaymentFailedEvent"
}
}
}
},
"responses": {
"200": {
"description": "Webhook processed successfully"
}
}
}
}
},
"components": {
"schemas": {
"Webhook": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"url": {
"type": "string",
"format": "uri",
"description": "Webhook endpoint URL"
},
"events": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of events this webhook subscribes to"
},
"isActive": {
"type": "boolean",
"description": "Whether the webhook is active"
},
"secret": {
"type": "string",
"description": "Webhook secret for signature validation"
},
"retryConfig": {
"$ref": "#/components/schemas/RetryConfig"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": ["id", "url", "events", "isActive", "createdAt", "updatedAt"]
},
"WebhookDetail": {
"allOf": [
{
"$ref": "#/components/schemas/Webhook"
},
{
"type": "object",
"properties": {
"deliveryStats": {
"$ref": "#/components/schemas/DeliveryStats"
},
"recentDeliveries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WebhookLog"
}
}
}
}
]
},
"CreateWebhookRequest": {
"type": "object",
"required": ["url", "events"],
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "Webhook endpoint URL"
},
"events": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of events to subscribe to"
},
"secret": {
"type": "string",
"minLength": 8,
"description": "Optional webhook secret for signature validation"
},
"retryConfig": {
"$ref": "#/components/schemas/RetryConfig"
}
}
},
"UpdateWebhookRequest": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"isActive": {
"type": "boolean"
},
"secret": {
"type": "string",
"minLength": 8
},
"retryConfig": {
"$ref": "#/components/schemas/RetryConfig"
}
}
},
"RetryConfig": {
"type": "object",
"properties": {
"maxRetries": {
"type": "integer",
"minimum": 0,
"maximum": 10,
"default": 3
},
"retryDelay": {
"type": "integer",
"minimum": 1,
"default": 60
},
"backoffMultiplier": {
"type": "number",
"minimum": 1,
"maximum": 5,
"default": 2
}
}
},
"DeliveryStats": {
"type": "object",
"properties": {
"totalDeliveries": {
"type": "integer",
"minimum": 0
},
"successfulDeliveries": {
"type": "integer",
"minimum": 0
},
"failedDeliveries": {
"type": "integer",
"minimum": 0
},
"pendingDeliveries": {
"type": "integer",
"minimum": 0
},
"successRate": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 100
},
"lastDeliveryAt": {
"type": "string",
"format": "date-time"
}
}
},
"WebhookLog": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"webhookId": {
"type": "string",
"format": "uuid"
},
"eventType": {
"type": "string"
},
"status": {
"type": "string",
"enum": ["success", "failed", "pending", "retrying"]
},
"httpStatus": {
"type": "integer"
},
"attempt": {
"type": "integer",
"minimum": 1
},
"responseTime": {
"type": "integer",
"description": "Response time in milliseconds"
},
"errorMessage": {
"type": "string"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"nextRetryAt": {
"type": "string",
"format": "date-time"
}
}
},
"WebhookTestResult": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"httpStatus": {
"type": "integer"
},
"responseTime": {
"type": "integer"
},
"response": {
"type": "string"
},
"error": {
"type": "string"
}
}
},
"UserCreatedEvent": {
"type": "object",
"properties": {
"eventId": {
"type": "string",
"format": "uuid"
},
"eventType": {
"type": "string",
"enum": ["user.created"]
},
"timestamp": {
"type": "string",
"format": "date-time"
},
"data": {
"type": "object",
"properties": {
"userId": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"username": {
"type": "string"
},
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
}
}
}
}
},
"OrderCompletedEvent": {
"type": "object",
"properties": {
"eventId": {
"type": "string",
"format": "uuid"
},
"eventType": {
"type": "string",
"enum": ["order.completed"]
},
"timestamp": {
"type": "string",
"format": "date-time"
},
"data": {
"type": "object",
"properties": {
"orderId": {
"type": "string",
"format": "uuid"
},
"orderNumber": {
"type": "string"
},
"userId": {
"type": "string",
"format": "uuid"
},
"total": {
"type": "number",
"format": "decimal"
},
"currency": {
"type": "string"
},
"itemCount": {
"type": "integer"
}
}
}
}
},
"PaymentFailedEvent": {
"type": "object",
"properties": {
"eventId": {
"type": "string",
"format": "uuid"
},
"eventType": {
"type": "string",
"enum": ["payment.failed"]
},
"timestamp": {
"type": "string",
"format": "date-time"
},
"data": {
"type": "object",
"properties": {
"paymentId": {
"type": "string",
"format": "uuid"
},
"orderId": {
"type": "string",
"format": "uuid"
},
"userId": {
"type": "string",
"format": "uuid"
},
"amount": {
"type": "number",
"format": "decimal"
},
"currency": {
"type": "string"
},
"failureReason": {
"type": "string"
},
"errorCode": {
"type": "string"
}
}
}
}
}
},
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT"
}
}
},
"tags": [
{
"name": "Webhooks",
"description": "Webhook management and event endpoints"
}
]
}