Offset Pagination
Offset-based pagination with page number and page size query parameters
API Definition
config/apis/steady_horse.rb
rb
# frozen_string_literal: true
Apiwork::API.define '/steady_horse' do
key_format :camel
export :openapi
export :typescript
export :zod
resources :products
endModels
app/models/steady_horse/product.rb
rb
# frozen_string_literal: true
module SteadyHorse
class Product < ApplicationRecord
validates :name, :price, :category, presence: true
end
endDatabase Table
| Column | Type | Nullable | Default |
|---|---|---|---|
| id | string | ||
| category | string | ||
| created_at | datetime | ||
| name | string | ||
| price | decimal | ||
| updated_at | datetime |
Representations
app/representations/steady_horse/product_representation.rb
rb
# frozen_string_literal: true
module SteadyHorse
class ProductRepresentation < Apiwork::Representation::Base
attribute :id
attribute :name, filterable: true, writable: true
attribute :price, sortable: true, writable: true
attribute :category, filterable: true, writable: true
attribute :created_at, sortable: true
attribute :updated_at, sortable: true
end
endContracts
app/contracts/steady_horse/product_contract.rb
rb
# frozen_string_literal: true
module SteadyHorse
class ProductContract < Apiwork::Contract::Base
representation ProductRepresentation
end
endControllers
app/controllers/steady_horse/products_controller.rb
rb
# frozen_string_literal: true
module SteadyHorse
class ProductsController < ApplicationController
before_action :set_product, only: %i[show update destroy]
def index
products = Product.all
expose products
end
def show
expose product
end
def create
product = Product.create(contract.body[:product])
expose product
end
def update
product.update(contract.body[:product])
expose product
end
def destroy
product.destroy
expose product
end
private
attr_reader :product
def set_product
@product = Product.find(params[:id])
end
end
endRequest Examples
First page (default)
Request
http
GET /steady_horse/productsResponse 200
json
{
"products": [
{
"id": "267adb6a-d0b4-54a7-a389-3b98a9eaa28c",
"name": "Wireless Keyboard",
"price": "49.99",
"category": "electronics",
"createdAt": "2024-01-01T12:00:00.000Z",
"updatedAt": "2024-01-01T12:00:00.000Z"
},
{
"id": "03df3eee-f5c2-5936-833e-1428b7014046",
"name": "USB-C Cable",
"price": "12.99",
"category": "electronics",
"createdAt": "2024-01-01T12:00:00.000Z",
"updatedAt": "2024-01-01T12:00:00.000Z"
},
{
"id": "9b201354-c4da-5ac1-b1af-277760ef44ae",
"name": "Desk Lamp",
"price": "34.99",
"category": "office",
"createdAt": "2024-01-01T12:00:00.000Z",
"updatedAt": "2024-01-01T12:00:00.000Z"
},
{
"id": "5ce18568-b578-5e99-b0fa-807d16a49d0f",
"name": "Notebook",
"price": "8.99",
"category": "office",
"createdAt": "2024-01-01T12:00:00.000Z",
"updatedAt": "2024-01-01T12:00:00.000Z"
},
{
"id": "de39e4db-cbc3-5392-a6d0-467af1c5b29d",
"name": "Monitor Stand",
"price": "79.99",
"category": "office",
"createdAt": "2024-01-01T12:00:00.000Z",
"updatedAt": "2024-01-01T12:00:00.000Z"
},
{
"id": "040ac486-238a-5942-abec-ad251c0cbb51",
"name": "Webcam",
"price": "59.99",
"category": "electronics",
"createdAt": "2024-01-01T12:00:00.000Z",
"updatedAt": "2024-01-01T12:00:00.000Z"
},
{
"id": "cb8c0234-a0a3-589a-9dba-12e95296dc98",
"name": "Mouse Pad",
"price": "14.99",
"category": "accessories",
"createdAt": "2024-01-01T12:00:00.000Z",
"updatedAt": "2024-01-01T12:00:00.000Z"
},
{
"id": "bf56b805-7bca-54ee-a90b-c9ebf84d9bec",
"name": "Headphones",
"price": "89.99",
"category": "electronics",
"createdAt": "2024-01-01T12:00:00.000Z",
"updatedAt": "2024-01-01T12:00:00.000Z"
}
],
"pagination": {
"items": 8,
"total": 1,
"current": 1,
"next": null,
"prev": null
}
}Specific page
Request
http
GET /steady_horse/products?page[number]=2&page[size]=3Response 200
json
{
"products": [
{
"id": "5ce18568-b578-5e99-b0fa-807d16a49d0f",
"name": "Notebook",
"price": "8.99",
"category": "office",
"createdAt": "2024-01-01T12:00:00.000Z",
"updatedAt": "2024-01-01T12:00:00.000Z"
},
{
"id": "de39e4db-cbc3-5392-a6d0-467af1c5b29d",
"name": "Monitor Stand",
"price": "79.99",
"category": "office",
"createdAt": "2024-01-01T12:00:00.000Z",
"updatedAt": "2024-01-01T12:00:00.000Z"
},
{
"id": "040ac486-238a-5942-abec-ad251c0cbb51",
"name": "Webcam",
"price": "59.99",
"category": "electronics",
"createdAt": "2024-01-01T12:00:00.000Z",
"updatedAt": "2024-01-01T12:00:00.000Z"
}
],
"pagination": {
"items": 8,
"total": 3,
"current": 2,
"next": 3,
"prev": 1
}
}Custom page size
Request
http
GET /steady_horse/products?page[size]=2Response 200
json
{
"products": [
{
"id": "267adb6a-d0b4-54a7-a389-3b98a9eaa28c",
"name": "Wireless Keyboard",
"price": "49.99",
"category": "electronics",
"createdAt": "2024-01-01T12:00:00.000Z",
"updatedAt": "2024-01-01T12:00:00.000Z"
},
{
"id": "03df3eee-f5c2-5936-833e-1428b7014046",
"name": "USB-C Cable",
"price": "12.99",
"category": "electronics",
"createdAt": "2024-01-01T12:00:00.000Z",
"updatedAt": "2024-01-01T12:00:00.000Z"
}
],
"pagination": {
"items": 5,
"total": 3,
"current": 1,
"next": 2,
"prev": null
}
}Generated Output
Introspection
json
{
"base_path": "/steady_horse",
"fingerprint": "f7693fa764c6617f",
"locales": [],
"enums": {
"error_layer": {
"deprecated": false,
"description": null,
"example": null,
"values": [
"http",
"contract",
"domain"
]
},
"sort_direction": {
"deprecated": false,
"description": null,
"example": null,
"values": [
"asc",
"desc"
]
}
},
"error_codes": {
"unprocessable_entity": {
"description": "Unprocessable Entity",
"status": 422
}
},
"info": null,
"resources": {
"products": {
"actions": {
"index": {
"deprecated": false,
"description": null,
"method": "get",
"operation_id": null,
"path": "/products",
"raises": [],
"request": {
"description": null,
"body": {},
"query": {
"filter": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": true,
"type": "union",
"discriminator": null,
"variants": [
{
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "reference",
"reference": "product_filter"
},
{
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "array",
"default": null,
"example": null,
"max": null,
"min": null,
"of": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "reference",
"reference": "product_filter"
},
"shape": {}
}
]
},
"page": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": true,
"type": "reference",
"reference": "product_page"
},
"sort": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": true,
"type": "union",
"discriminator": null,
"variants": [
{
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "reference",
"reference": "product_sort"
},
{
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "array",
"default": null,
"example": null,
"max": null,
"min": null,
"of": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "reference",
"reference": "product_sort"
},
"shape": {}
}
]
}
}
},
"response": {
"description": null,
"body": {
"deprecated": null,
"description": null,
"nullable": null,
"optional": null,
"type": "object",
"partial": null,
"shape": {
"meta": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": true,
"type": "object",
"partial": false,
"shape": {}
},
"pagination": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "reference",
"reference": "offset_pagination"
},
"products": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "array",
"default": null,
"example": null,
"max": null,
"min": null,
"of": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "reference",
"reference": "product"
},
"shape": {}
}
}
},
"no_content": false
},
"summary": null,
"tags": []
},
"show": {
"deprecated": false,
"description": null,
"method": "get",
"operation_id": null,
"path": "/products/:id",
"raises": [],
"request": {
"description": null,
"body": {},
"query": {}
},
"response": {
"description": null,
"body": {
"deprecated": null,
"description": null,
"nullable": null,
"optional": null,
"type": "object",
"partial": null,
"shape": {
"meta": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": true,
"type": "object",
"partial": false,
"shape": {}
},
"product": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "reference",
"reference": "product"
}
}
},
"no_content": false
},
"summary": null,
"tags": []
},
"create": {
"deprecated": false,
"description": null,
"method": "post",
"operation_id": null,
"path": "/products",
"raises": [
"unprocessable_entity"
],
"request": {
"description": null,
"body": {
"product": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "reference",
"reference": "product_create_payload"
}
},
"query": {}
},
"response": {
"description": null,
"body": {
"deprecated": null,
"description": null,
"nullable": null,
"optional": null,
"type": "object",
"partial": null,
"shape": {
"meta": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": true,
"type": "object",
"partial": false,
"shape": {}
},
"product": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "reference",
"reference": "product"
}
}
},
"no_content": false
},
"summary": null,
"tags": []
},
"update": {
"deprecated": false,
"description": null,
"method": "patch",
"operation_id": null,
"path": "/products/:id",
"raises": [
"unprocessable_entity"
],
"request": {
"description": null,
"body": {
"product": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "reference",
"reference": "product_update_payload"
}
},
"query": {}
},
"response": {
"description": null,
"body": {
"deprecated": null,
"description": null,
"nullable": null,
"optional": null,
"type": "object",
"partial": null,
"shape": {
"meta": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": true,
"type": "object",
"partial": false,
"shape": {}
},
"product": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "reference",
"reference": "product"
}
}
},
"no_content": false
},
"summary": null,
"tags": []
},
"destroy": {
"deprecated": false,
"description": null,
"method": "delete",
"operation_id": null,
"path": "/products/:id",
"raises": [],
"request": {
"description": null,
"body": {},
"query": {}
},
"response": {
"description": null,
"body": null,
"no_content": true
},
"summary": null,
"tags": []
}
},
"identifier": "products",
"parent_identifiers": [],
"path": "products",
"resources": {}
}
},
"types": {
"error": {
"deprecated": false,
"description": null,
"discriminator": null,
"example": null,
"extends": [],
"shape": {
"issues": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "array",
"default": null,
"example": null,
"max": null,
"min": null,
"of": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "reference",
"reference": "error_issue"
},
"shape": {}
},
"layer": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "reference",
"reference": "error_layer"
}
},
"type": "object",
"variants": []
},
"error_issue": {
"deprecated": false,
"description": null,
"discriminator": null,
"example": null,
"extends": [],
"shape": {
"code": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "string",
"default": null,
"example": null,
"format": null,
"max": null,
"min": null
},
"detail": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "string",
"default": null,
"example": null,
"format": null,
"max": null,
"min": null
},
"meta": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "object",
"partial": false,
"shape": {}
},
"path": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "array",
"default": null,
"example": null,
"max": null,
"min": null,
"of": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "union",
"discriminator": null,
"variants": [
{
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "string",
"default": null,
"example": null,
"format": null,
"max": null,
"min": null
},
{
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "integer",
"default": null,
"example": null,
"format": null,
"max": null,
"min": null
}
]
},
"shape": {}
},
"pointer": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "string",
"default": null,
"example": null,
"format": null,
"max": null,
"min": null
}
},
"type": "object",
"variants": []
},
"offset_pagination": {
"deprecated": false,
"description": null,
"discriminator": null,
"example": null,
"extends": [],
"shape": {
"current": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "integer",
"default": null,
"example": null,
"format": null,
"max": null,
"min": null
},
"items": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "integer",
"default": null,
"example": null,
"format": null,
"max": null,
"min": null
},
"next": {
"deprecated": false,
"description": null,
"nullable": true,
"optional": true,
"type": "integer",
"default": null,
"example": null,
"format": null,
"max": null,
"min": null
},
"prev": {
"deprecated": false,
"description": null,
"nullable": true,
"optional": true,
"type": "integer",
"default": null,
"example": null,
"format": null,
"max": null,
"min": null
},
"total": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "integer",
"default": null,
"example": null,
"format": null,
"max": null,
"min": null
}
},
"type": "object",
"variants": []
},
"product": {
"deprecated": false,
"description": null,
"discriminator": null,
"example": null,
"extends": [],
"shape": {
"category": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "string",
"default": null,
"example": null,
"format": null,
"max": null,
"min": null
},
"created_at": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "datetime",
"default": null,
"example": null
},
"id": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "string",
"default": null,
"example": null,
"format": null,
"max": null,
"min": null
},
"name": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "string",
"default": null,
"example": null,
"format": null,
"max": null,
"min": null
},
"price": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "decimal",
"default": null,
"example": null,
"max": null,
"min": null
},
"updated_at": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "datetime",
"default": null,
"example": null
}
},
"type": "object",
"variants": []
},
"product_create_payload": {
"deprecated": false,
"description": null,
"discriminator": null,
"example": null,
"extends": [],
"shape": {
"category": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "string",
"default": null,
"example": null,
"format": null,
"max": null,
"min": null
},
"name": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "string",
"default": null,
"example": null,
"format": null,
"max": null,
"min": null
},
"price": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "decimal",
"default": null,
"example": null,
"max": 99999999.99,
"min": -99999999.99
}
},
"type": "object",
"variants": []
},
"product_filter": {
"deprecated": false,
"description": null,
"discriminator": null,
"example": null,
"extends": [],
"shape": {
"AND": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": true,
"type": "array",
"default": null,
"example": null,
"max": null,
"min": null,
"of": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "reference",
"reference": "product_filter"
},
"shape": {}
},
"NOT": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": true,
"type": "reference",
"reference": "product_filter"
},
"OR": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": true,
"type": "array",
"default": null,
"example": null,
"max": null,
"min": null,
"of": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "reference",
"reference": "product_filter"
},
"shape": {}
},
"category": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": true,
"type": "union",
"discriminator": null,
"variants": [
{
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "string",
"default": null,
"example": null,
"format": null,
"max": null,
"min": null
},
{
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "reference",
"reference": "string_filter"
}
]
},
"name": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": true,
"type": "union",
"discriminator": null,
"variants": [
{
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "string",
"default": null,
"example": null,
"format": null,
"max": null,
"min": null
},
{
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "reference",
"reference": "string_filter"
}
]
}
},
"type": "object",
"variants": []
},
"product_page": {
"deprecated": false,
"description": null,
"discriminator": null,
"example": null,
"extends": [],
"shape": {
"number": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": true,
"type": "integer",
"default": null,
"example": null,
"format": null,
"max": null,
"min": 1
},
"size": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": true,
"type": "integer",
"default": null,
"example": null,
"format": null,
"max": 100,
"min": 1
}
},
"type": "object",
"variants": []
},
"product_sort": {
"deprecated": false,
"description": null,
"discriminator": null,
"example": null,
"extends": [],
"shape": {
"created_at": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": true,
"type": "reference",
"reference": "sort_direction"
},
"price": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": true,
"type": "reference",
"reference": "sort_direction"
},
"updated_at": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": true,
"type": "reference",
"reference": "sort_direction"
}
},
"type": "object",
"variants": []
},
"product_update_payload": {
"deprecated": false,
"description": null,
"discriminator": null,
"example": null,
"extends": [],
"shape": {
"category": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": true,
"type": "string",
"default": null,
"example": null,
"format": null,
"max": null,
"min": null
},
"name": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": true,
"type": "string",
"default": null,
"example": null,
"format": null,
"max": null,
"min": null
},
"price": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": true,
"type": "decimal",
"default": null,
"example": null,
"max": 99999999.99,
"min": -99999999.99
}
},
"type": "object",
"variants": []
},
"string_filter": {
"deprecated": false,
"description": null,
"discriminator": null,
"example": null,
"extends": [],
"shape": {
"contains": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": true,
"type": "string",
"default": null,
"example": null,
"format": null,
"max": null,
"min": null
},
"ends_with": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": true,
"type": "string",
"default": null,
"example": null,
"format": null,
"max": null,
"min": null
},
"eq": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": true,
"type": "string",
"default": null,
"example": null,
"format": null,
"max": null,
"min": null
},
"in": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": true,
"type": "array",
"default": null,
"example": null,
"max": null,
"min": null,
"of": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "string",
"default": null,
"example": null,
"format": null,
"max": null,
"min": null
},
"shape": {}
},
"starts_with": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": true,
"type": "string",
"default": null,
"example": null,
"format": null,
"max": null,
"min": null
}
},
"type": "object",
"variants": []
}
}
}TypeScript
ts
export interface Error {
issues: ErrorIssue[];
layer: ErrorLayer;
}
export interface ErrorIssue {
code: string;
detail: string;
meta: Record<string, unknown>;
path: (number | string)[];
pointer: string;
}
export type ErrorLayer = 'contract' | 'domain' | 'http';
export interface OffsetPagination {
current: number;
items: number;
next: null | number;
prev: null | number;
total: number;
}
export interface Product {
category: string;
createdAt: string;
id: string;
name: string;
price: number;
updatedAt: string;
}
export interface ProductCreatePayload {
category: string;
name: string;
price: number;
}
export interface ProductFilter {
AND?: ProductFilter[];
NOT?: ProductFilter;
OR?: ProductFilter[];
category?: StringFilter | string;
name?: StringFilter | string;
}
export interface ProductPage {
number?: number;
size?: number;
}
export interface ProductSort {
createdAt?: SortDirection;
price?: SortDirection;
updatedAt?: SortDirection;
}
export interface ProductUpdatePayload {
category?: string;
name?: string;
price?: number;
}
export interface ProductsCreateRequest {
body: ProductsCreateRequestBody;
}
export interface ProductsCreateRequestBody {
product: ProductCreatePayload;
}
export type ProductsCreateResponse =
| { status: 200; body: ProductsCreateResponseBody }
| { status: 422; body: Error };
export type ProductsCreateResponseBody = { meta?: Record<string, unknown>; product: Product };
export type ProductsDestroyResponse = { status: 204 };
export interface ProductsIndexRequest {
query: ProductsIndexRequestQuery;
}
export interface ProductsIndexRequestQuery {
filter?: ProductFilter | ProductFilter[];
page?: ProductPage;
sort?: ProductSort | ProductSort[];
}
export type ProductsIndexResponse = { status: 200; body: ProductsIndexResponseBody };
export type ProductsIndexResponseBody = { meta?: Record<string, unknown>; pagination: OffsetPagination; products: Product[] };
export type ProductsShowResponse = { status: 200; body: ProductsShowResponseBody };
export type ProductsShowResponseBody = { meta?: Record<string, unknown>; product: Product };
export interface ProductsUpdateRequest {
body: ProductsUpdateRequestBody;
}
export interface ProductsUpdateRequestBody {
product: ProductUpdatePayload;
}
export type ProductsUpdateResponse =
| { status: 200; body: ProductsUpdateResponseBody }
| { status: 422; body: Error };
export type ProductsUpdateResponseBody = { meta?: Record<string, unknown>; product: Product };
export type SortDirection = 'asc' | 'desc';
export interface StringFilter {
contains?: string;
endsWith?: string;
eq?: string;
in?: string[];
startsWith?: string;
}Zod
ts
import { z } from 'zod';
export const ErrorLayerSchema = z.enum(['contract', 'domain', 'http']);
export const SortDirectionSchema = z.enum(['asc', 'desc']);
export const ProductFilterSchema: z.ZodType<ProductFilter> = z.lazy(() => z.object({
AND: z.array(ProductFilterSchema).optional(),
NOT: ProductFilterSchema.optional(),
OR: z.array(ProductFilterSchema).optional(),
category: z.union([z.string(), StringFilterSchema]).optional(),
name: z.union([z.string(), StringFilterSchema]).optional()
}));
export const ErrorIssueSchema = z.object({
code: z.string(),
detail: z.string(),
meta: z.record(z.string(), z.unknown()),
path: z.array(z.union([z.string(), z.number().int()])),
pointer: z.string()
});
export const OffsetPaginationSchema = z.object({
current: z.number().int(),
items: z.number().int(),
next: z.number().int().nullable().default(null),
prev: z.number().int().nullable().default(null),
total: z.number().int()
});
export const ProductSchema = z.object({
category: z.string(),
createdAt: z.iso.datetime(),
id: z.string(),
name: z.string(),
price: z.number(),
updatedAt: z.iso.datetime()
});
export const ProductCreatePayloadSchema = z.object({
category: z.string(),
name: z.string(),
price: z.number().min(-99999999.99).max(99999999.99)
});
export const ProductPageSchema = z.object({
number: z.number().int().min(1).optional(),
size: z.number().int().min(1).max(100).optional()
});
export const ProductSortSchema = z.object({
createdAt: SortDirectionSchema.optional(),
price: SortDirectionSchema.optional(),
updatedAt: SortDirectionSchema.optional()
});
export const ProductUpdatePayloadSchema = z.object({
category: z.string().optional(),
name: z.string().optional(),
price: z.number().min(-99999999.99).max(99999999.99).optional()
});
export const StringFilterSchema = z.object({
contains: z.string().optional(),
endsWith: z.string().optional(),
eq: z.string().optional(),
in: z.array(z.string()).optional(),
startsWith: z.string().optional()
});
export const ErrorSchema = z.object({
issues: z.array(ErrorIssueSchema),
layer: ErrorLayerSchema
});
export const ProductsIndexRequestQuerySchema = z.object({
filter: z.union([ProductFilterSchema, z.array(ProductFilterSchema)]).optional(),
page: ProductPageSchema.optional(),
sort: z.union([ProductSortSchema, z.array(ProductSortSchema)]).optional()
});
export const ProductsIndexRequestSchema = z.object({
query: ProductsIndexRequestQuerySchema
});
export const ProductsIndexResponseBodySchema = z.object({ meta: z.record(z.string(), z.unknown()).optional(), pagination: OffsetPaginationSchema, products: z.array(ProductSchema) });
export const ProductsShowResponseBodySchema = z.object({ meta: z.record(z.string(), z.unknown()).optional(), product: ProductSchema });
export const ProductsCreateRequestBodySchema = z.object({
product: ProductCreatePayloadSchema
});
export const ProductsCreateRequestSchema = z.object({
body: ProductsCreateRequestBodySchema
});
export const ProductsCreateResponseBodySchema = z.object({ meta: z.record(z.string(), z.unknown()).optional(), product: ProductSchema });
export const ProductsUpdateRequestBodySchema = z.object({
product: ProductUpdatePayloadSchema
});
export const ProductsUpdateRequestSchema = z.object({
body: ProductsUpdateRequestBodySchema
});
export const ProductsUpdateResponseBodySchema = z.object({ meta: z.record(z.string(), z.unknown()).optional(), product: ProductSchema });
export const ProductsIndexResponseSchema = z.object({ status: z.literal(200), body: ProductsIndexResponseBodySchema });
export const ProductsShowResponseSchema = z.object({ status: z.literal(200), body: ProductsShowResponseBodySchema });
export const ProductsCreateResponseSchema = z.discriminatedUnion('status', [
z.object({ status: z.literal(200), body: ProductsCreateResponseBodySchema }),
z.object({ status: z.literal(422), body: ErrorSchema })
]);
export const ProductsUpdateResponseSchema = z.discriminatedUnion('status', [
z.object({ status: z.literal(200), body: ProductsUpdateResponseBodySchema }),
z.object({ status: z.literal(422), body: ErrorSchema })
]);
export const ProductsDestroyResponseSchema = z.object({ status: z.literal(204) });
export interface Error {
issues: ErrorIssue[];
layer: ErrorLayer;
}
export interface ErrorIssue {
code: string;
detail: string;
meta: Record<string, unknown>;
path: (number | string)[];
pointer: string;
}
export type ErrorLayer = 'contract' | 'domain' | 'http';
export interface OffsetPagination {
current: number;
items: number;
next: null | number;
prev: null | number;
total: number;
}
export interface Product {
category: string;
createdAt: string;
id: string;
name: string;
price: number;
updatedAt: string;
}
export interface ProductCreatePayload {
category: string;
name: string;
price: number;
}
export interface ProductFilter {
AND?: ProductFilter[];
NOT?: ProductFilter;
OR?: ProductFilter[];
category?: StringFilter | string;
name?: StringFilter | string;
}
export interface ProductPage {
number?: number;
size?: number;
}
export interface ProductSort {
createdAt?: SortDirection;
price?: SortDirection;
updatedAt?: SortDirection;
}
export interface ProductUpdatePayload {
category?: string;
name?: string;
price?: number;
}
export interface ProductsCreateRequest {
body: ProductsCreateRequestBody;
}
export interface ProductsCreateRequestBody {
product: ProductCreatePayload;
}
export type ProductsCreateResponse =
| { status: 200; body: ProductsCreateResponseBody }
| { status: 422; body: Error };
export type ProductsCreateResponseBody = { meta?: Record<string, unknown>; product: Product };
export type ProductsDestroyResponse = { status: 204 };
export interface ProductsIndexRequest {
query: ProductsIndexRequestQuery;
}
export interface ProductsIndexRequestQuery {
filter?: ProductFilter | ProductFilter[];
page?: ProductPage;
sort?: ProductSort | ProductSort[];
}
export type ProductsIndexResponse = { status: 200; body: ProductsIndexResponseBody };
export type ProductsIndexResponseBody = { meta?: Record<string, unknown>; pagination: OffsetPagination; products: Product[] };
export type ProductsShowResponse = { status: 200; body: ProductsShowResponseBody };
export type ProductsShowResponseBody = { meta?: Record<string, unknown>; product: Product };
export interface ProductsUpdateRequest {
body: ProductsUpdateRequestBody;
}
export interface ProductsUpdateRequestBody {
product: ProductUpdatePayload;
}
export type ProductsUpdateResponse =
| { status: 200; body: ProductsUpdateResponseBody }
| { status: 422; body: Error };
export type ProductsUpdateResponseBody = { meta?: Record<string, unknown>; product: Product };
export type SortDirection = 'asc' | 'desc';
export interface StringFilter {
contains?: string;
endsWith?: string;
eq?: string;
in?: string[];
startsWith?: string;
}OpenAPI
yml
---
openapi: 3.1.0
info:
title: "/steady_horse"
version: 1.0.0
paths:
"/products":
get:
operationId: productsIndex
parameters:
- in: query
name: filter
required: false
schema:
oneOf:
- "$ref": "#/components/schemas/productFilter"
- items:
"$ref": "#/components/schemas/productFilter"
type: array
- in: query
name: page
required: false
schema:
"$ref": "#/components/schemas/productPage"
- in: query
name: sort
required: false
schema:
oneOf:
- "$ref": "#/components/schemas/productSort"
- items:
"$ref": "#/components/schemas/productSort"
type: array
responses:
'200':
content:
application/json:
schema:
properties:
meta:
properties: {}
type: object
pagination:
"$ref": "#/components/schemas/offsetPagination"
products:
items:
"$ref": "#/components/schemas/product"
type: array
type: object
required:
- pagination
- products
description: ''
post:
operationId: productsCreate
requestBody:
content:
application/json:
schema:
properties:
product:
"$ref": "#/components/schemas/productCreatePayload"
type: object
required:
- product
required: true
responses:
'200':
content:
application/json:
schema:
properties:
meta:
properties: {}
type: object
product:
"$ref": "#/components/schemas/product"
type: object
required:
- product
description: ''
'422':
description: Unprocessable Entity
content:
application/json:
schema:
properties:
issues:
items:
"$ref": "#/components/schemas/error"
type: array
required:
- issues
type: object
"/products/{id}":
get:
operationId: productsShow
parameters:
- in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties:
meta:
properties: {}
type: object
product:
"$ref": "#/components/schemas/product"
type: object
required:
- product
description: ''
patch:
operationId: productsUpdate
parameters:
- in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
product:
"$ref": "#/components/schemas/productUpdatePayload"
type: object
required:
- product
required: true
responses:
'200':
content:
application/json:
schema:
properties:
meta:
properties: {}
type: object
product:
"$ref": "#/components/schemas/product"
type: object
required:
- product
description: ''
'422':
description: Unprocessable Entity
content:
application/json:
schema:
properties:
issues:
items:
"$ref": "#/components/schemas/error"
type: array
required:
- issues
type: object
delete:
operationId: productsDestroy
parameters:
- in: path
name: id
required: true
schema:
type: string
responses:
'204':
description: ''
components:
schemas:
error:
properties:
issues:
items:
"$ref": "#/components/schemas/errorIssue"
type: array
layer:
enum:
- http
- contract
- domain
type: string
type: object
required:
- issues
- layer
errorIssue:
properties:
code:
type: string
detail:
type: string
meta:
properties: {}
type: object
path:
items:
oneOf:
- type: string
- type: integer
type: array
pointer:
type: string
type: object
required:
- code
- detail
- meta
- path
- pointer
offsetPagination:
properties:
current:
type: integer
items:
type: integer
next:
type:
- integer
- 'null'
default:
prev:
type:
- integer
- 'null'
default:
total:
type: integer
type: object
required:
- current
- items
- total
product:
properties:
category:
type: string
createdAt:
type: string
format: date-time
id:
type: string
name:
type: string
price:
type: number
updatedAt:
type: string
format: date-time
type: object
required:
- category
- createdAt
- id
- name
- price
- updatedAt
productCreatePayload:
properties:
category:
type: string
name:
type: string
price:
type: number
minimum: -99999999.99
maximum: 99999999.99
type: object
required:
- category
- name
- price
productFilter:
properties:
AND:
items:
"$ref": "#/components/schemas/productFilter"
type: array
NOT:
"$ref": "#/components/schemas/productFilter"
OR:
items:
"$ref": "#/components/schemas/productFilter"
type: array
category:
oneOf:
- type: string
- "$ref": "#/components/schemas/stringFilter"
name:
oneOf:
- type: string
- "$ref": "#/components/schemas/stringFilter"
type: object
productPage:
properties:
number:
type: integer
minimum: 1
size:
type: integer
minimum: 1
maximum: 100
type: object
productSort:
properties:
createdAt:
enum:
- asc
- desc
type: string
price:
enum:
- asc
- desc
type: string
updatedAt:
enum:
- asc
- desc
type: string
type: object
productUpdatePayload:
properties:
category:
type: string
name:
type: string
price:
type: number
minimum: -99999999.99
maximum: 99999999.99
type: object
stringFilter:
properties:
contains:
type: string
endsWith:
type: string
eq:
type: string
in:
items:
type: string
type: array
startsWith:
type: string
type: object