Sample OpenAPI Spec
Need a solid, no-fluff OpenAPI spec to demo, test, or kickstart your next project?
We put together a clean, OpenAPI 3.1.0 spec for a small ecommerce app, this is just enough to cover real-world flows like user auth, product browsing, cart updates, and placing orders. It’s ideal for QA automation, frontend mocks, teaching API design, or any quick integration use-case.
Sample OpenAPI Spec
Here’s the spec to copy 👇 (or download YAML, JSON)
openapi: 3.1.0
info:
title: E-commerce API
version: 1.0.0
description: |
This is an e-commerce API spec for a storefront.
It includes authentication, product browsing, cart, and checkout operations.
Auth is token-based. Explore, test, and mock this API freely.
servers:
- url: https://api.demo-ecommerce.com/v1
description: Production environment
- url: https://api.dev.demo-ecommerce.com/v1
description: Development environment
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
schemas:
Product:
type: object
required: [id, name, price, stock, category]
properties:
id:
type: string
format: uuid
example: eda5cbc1-a615-4da5-ae73-4a33a9acfb6a
name:
type: string
example: Worry Management
description:
type: string
example: Mr street sell would civil. People through shake southern force.
price:
type: number
format: float
example: 91.37
category:
type: string
example: wrong
image_url:
type: string
format: uri
example: https://dummyimage.com/766x809
stock:
type: integer
example: 94
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
CartItem:
type: object
required: [product_id, quantity]
properties:
product_id:
type: string
format: uuid
quantity:
type: integer
minimum: 1
Address:
type: object
required: [line1, city, state, postal_code, country]
properties:
line1:
type: string
line2:
type: string
city:
type: string
state:
type: string
postal_code:
type: string
country:
type: string
Order:
type: object
required: [id, items, total_amount, status, created_at]
properties:
id:
type: string
format: uuid
items:
type: array
items:
$ref: '#/components/schemas/CartItem'
total_amount:
type: number
status:
type: string
enum: [pending, confirmed, shipped, delivered]
created_at:
type: string
format: date-time
paths:
/auth/register:
post:
summary: Create a new user account
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [email, password]
properties:
email:
type: string
format: email
password:
type: string
format: password
name:
type: string
responses:
'201':
description: User created
'400':
description: Invalid input
/auth/login:
post:
summary: Login and get access token
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [email, password]
properties:
email:
type: string
password:
type: string
responses:
'200':
description: Authenticated successfully
'401':
description: Unauthorized
/products:
get:
summary: List all products with filters
parameters:
- name: category
in: query
schema:
type: string
- name: search
in: query
schema:
type: string
- name: min_price
in: query
schema:
type: number
- name: max_price
in: query
schema:
type: number
responses:
'200':
description: List of products
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Product'
/products/{id}:
get:
summary: Get product details by ID
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Product details
content:
application/json:
schema:
$ref: '#/components/schemas/Product'
/cart:
get:
summary: Get current user's cart
security:
- BearerAuth: []
responses:
'200':
description: Your cart items
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CartItem'
/cart/items:
post:
summary: Add item to cart
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CartItem'
responses:
'200':
description: Item added to cart
/checkout:
post:
summary: Checkout and place order
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [address_id, payment_method_id]
properties:
address_id:
type: string
payment_method_id:
type: string
responses:
'201':
description: Order created
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
/orders:
get:
summary: List your past orders
security:
- BearerAuth: []
responses:
'200':
description: Order history
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Order'
/orders/{orderId}:
get:
summary: Get order details
security:
- BearerAuth: []
parameters:
- name: orderId
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Order detail
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
/addresses:
get:
summary: Get your saved addresses
security:
- BearerAuth: []
responses:
'200':
description: List of saved addresses
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Address'
post:
summary: Add a new address
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Address'
responses:
'201':
description: Address added
You can mock it instantly on Beeceptor, which spins up a live API server from any OpenAPI spec, no hosting needed.
What’s in the Spec?
These APIs represent a customer-facing e-commerce feature set. The features included are listed below:
POST /auth/register: Create accountPOST /auth/login: Get bearer tokenGET /products: List with filters like category or price rangeGET /products/{id}: Fetch product detailsGET /cart: View items in cartPOST /cart/items: Add an item to the cartPOST /checkout: Finalize the purchase, with checkout operation. No payment integration here.GET /orders: List user’s recent ordersGET /orders/{id}: Get specific order infoGET /addresses: Retrieve shipping infoPOST /addresses: Save the shipping info