Type Imports
Share types between contracts with import
API Definition
config/apis/calm_turtle.rb
rb
# frozen_string_literal: true
Apiwork::API.define '/calm_turtle' do
key_format :camel
export :openapi
export :typescript
export :zod
resources :customers
resources :orders
endModels
app/models/calm_turtle/customer.rb
rb
# frozen_string_literal: true
module CalmTurtle
class Customer < ApplicationRecord
validates :name, presence: true
end
endDatabase Table
| Column | Type | Nullable | Default |
|---|---|---|---|
| id | string | ||
| billing_address | json | ✓ | |
| created_at | datetime | ||
| name | string | ||
| updated_at | datetime |
app/models/calm_turtle/order.rb
rb
# frozen_string_literal: true
module CalmTurtle
class Order < ApplicationRecord
validates :order_number, presence: true
end
endDatabase Table
| Column | Type | Nullable | Default |
|---|---|---|---|
| id | string | ||
| created_at | datetime | ||
| order_number | string | ||
| shipping_address | json | ✓ | |
| updated_at | datetime |
Contracts
app/contracts/calm_turtle/customer_contract.rb
rb
# frozen_string_literal: true
module CalmTurtle
class CustomerContract < Apiwork::Contract::Base
object :address do
string :street
string :city
string :country
end
object :customer do
uuid :id
string :name
reference :billing_address, to: :address
datetime :created_at
datetime :updated_at
end
object :create_payload do
string :name
reference :billing_address, to: :address
end
action :create do
request do
body do
reference :customer, to: :create_payload
end
end
response do
body do
reference :customer
end
end
end
end
endapp/contracts/calm_turtle/order_contract.rb
rb
# frozen_string_literal: true
module CalmTurtle
class OrderContract < Apiwork::Contract::Base
import CustomerContract, as: :customer
object :order do
uuid :id
string :order_number
reference :shipping_address, to: :customer_address
datetime :created_at
datetime :updated_at
end
object :create_payload do
string :order_number
reference :shipping_address, to: :customer_address
end
action :create do
request do
body do
reference :order, to: :create_payload
end
end
response do
body do
reference :order
end
end
end
end
endControllers
app/controllers/calm_turtle/orders_controller.rb
rb
# frozen_string_literal: true
module CalmTurtle
class OrdersController < ApplicationController
def create
order = Order.create(contract.body[:order])
expose({ order: })
end
end
endRequest Examples
Create order
Request
http
POST /calm_turtle/orders
Content-Type: application/json
{
"order": {
"orderNumber": "ORD-001",
"shippingAddress": {
"street": "456 Oak Ave",
"city": "Shelbyville",
"country": "US"
}
}
}Response 201
json
{
"order": {
"id": "f951f663-b887-5470-8c0c-03e090cd26eb",
"createdAt": "2024-01-01T12:00:00.000Z",
"orderNumber": "ORD-001",
"shippingAddress": {
"street": "456 Oak Ave",
"city": "Shelbyville",
"country": "US"
},
"updatedAt": "2024-01-01T12:00:00.000Z"
}
}Generated Output
Introspection
json
{
"base_path": "/calm_turtle",
"fingerprint": "2e3af20641d12b5f",
"locales": [],
"enums": {
"error_layer": {
"deprecated": false,
"description": null,
"example": null,
"values": [
"http",
"contract",
"domain"
]
}
},
"error_codes": {},
"info": null,
"resources": {
"customers": {
"actions": {
"index": {
"deprecated": null,
"description": null,
"method": "get",
"operation_id": null,
"path": "/customers",
"raises": [],
"request": {
"description": null,
"body": {},
"query": {}
},
"response": {
"description": null,
"body": {
"deprecated": null,
"description": null,
"nullable": null,
"optional": null,
"type": null
},
"no_content": false
},
"summary": null,
"tags": []
},
"show": {
"deprecated": null,
"description": null,
"method": "get",
"operation_id": null,
"path": "/customers/:id",
"raises": [],
"request": {
"description": null,
"body": {},
"query": {}
},
"response": {
"description": null,
"body": {
"deprecated": null,
"description": null,
"nullable": null,
"optional": null,
"type": null
},
"no_content": false
},
"summary": null,
"tags": []
},
"create": {
"deprecated": false,
"description": null,
"method": "post",
"operation_id": null,
"path": "/customers",
"raises": [],
"request": {
"description": null,
"body": {
"customer": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "reference",
"reference": "customer_create_payload"
}
},
"query": {}
},
"response": {
"description": null,
"body": {
"deprecated": null,
"description": null,
"nullable": null,
"optional": null,
"type": "object",
"partial": null,
"shape": {
"customer": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "reference",
"reference": "customer"
}
}
},
"no_content": false
},
"summary": null,
"tags": []
},
"update": {
"deprecated": null,
"description": null,
"method": "patch",
"operation_id": null,
"path": "/customers/:id",
"raises": [],
"request": {
"description": null,
"body": {},
"query": {}
},
"response": {
"description": null,
"body": {
"deprecated": null,
"description": null,
"nullable": null,
"optional": null,
"type": null
},
"no_content": false
},
"summary": null,
"tags": []
},
"destroy": {
"deprecated": null,
"description": null,
"method": "delete",
"operation_id": null,
"path": "/customers/:id",
"raises": [],
"request": {
"description": null,
"body": {},
"query": {}
},
"response": {
"description": null,
"body": {
"deprecated": null,
"description": null,
"nullable": null,
"optional": null,
"type": null
},
"no_content": false
},
"summary": null,
"tags": []
}
},
"identifier": "customers",
"parent_identifiers": [],
"path": "customers",
"resources": {}
},
"orders": {
"actions": {
"index": {
"deprecated": null,
"description": null,
"method": "get",
"operation_id": null,
"path": "/orders",
"raises": [],
"request": {
"description": null,
"body": {},
"query": {}
},
"response": {
"description": null,
"body": {
"deprecated": null,
"description": null,
"nullable": null,
"optional": null,
"type": null
},
"no_content": false
},
"summary": null,
"tags": []
},
"show": {
"deprecated": null,
"description": null,
"method": "get",
"operation_id": null,
"path": "/orders/:id",
"raises": [],
"request": {
"description": null,
"body": {},
"query": {}
},
"response": {
"description": null,
"body": {
"deprecated": null,
"description": null,
"nullable": null,
"optional": null,
"type": null
},
"no_content": false
},
"summary": null,
"tags": []
},
"create": {
"deprecated": false,
"description": null,
"method": "post",
"operation_id": null,
"path": "/orders",
"raises": [],
"request": {
"description": null,
"body": {
"order": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "reference",
"reference": "order_create_payload"
}
},
"query": {}
},
"response": {
"description": null,
"body": {
"deprecated": null,
"description": null,
"nullable": null,
"optional": null,
"type": "object",
"partial": null,
"shape": {
"order": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "reference",
"reference": "order"
}
}
},
"no_content": false
},
"summary": null,
"tags": []
},
"update": {
"deprecated": null,
"description": null,
"method": "patch",
"operation_id": null,
"path": "/orders/:id",
"raises": [],
"request": {
"description": null,
"body": {},
"query": {}
},
"response": {
"description": null,
"body": {
"deprecated": null,
"description": null,
"nullable": null,
"optional": null,
"type": null
},
"no_content": false
},
"summary": null,
"tags": []
},
"destroy": {
"deprecated": null,
"description": null,
"method": "delete",
"operation_id": null,
"path": "/orders/:id",
"raises": [],
"request": {
"description": null,
"body": {},
"query": {}
},
"response": {
"description": null,
"body": {
"deprecated": null,
"description": null,
"nullable": null,
"optional": null,
"type": null
},
"no_content": false
},
"summary": null,
"tags": []
}
},
"identifier": "orders",
"parent_identifiers": [],
"path": "orders",
"resources": {}
}
},
"types": {
"customer": {
"deprecated": false,
"description": null,
"discriminator": null,
"example": null,
"extends": [],
"shape": {
"billing_address": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "reference",
"reference": "customer_address"
},
"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": "uuid",
"default": null,
"example": null
},
"name": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "string",
"default": null,
"example": null,
"format": null,
"max": null,
"min": null
},
"updated_at": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "datetime",
"default": null,
"example": null
}
},
"type": "object",
"variants": []
},
"customer_address": {
"deprecated": false,
"description": null,
"discriminator": null,
"example": null,
"extends": [],
"shape": {
"city": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "string",
"default": null,
"example": null,
"format": null,
"max": null,
"min": null
},
"country": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "string",
"default": null,
"example": null,
"format": null,
"max": null,
"min": null
},
"street": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "string",
"default": null,
"example": null,
"format": null,
"max": null,
"min": null
}
},
"type": "object",
"variants": []
},
"customer_create_payload": {
"deprecated": false,
"description": null,
"discriminator": null,
"example": null,
"extends": [],
"shape": {
"billing_address": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "reference",
"reference": "customer_address"
},
"name": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "string",
"default": null,
"example": null,
"format": null,
"max": null,
"min": null
}
},
"type": "object",
"variants": []
},
"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": []
},
"order": {
"deprecated": false,
"description": null,
"discriminator": null,
"example": null,
"extends": [],
"shape": {
"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": "uuid",
"default": null,
"example": null
},
"order_number": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "string",
"default": null,
"example": null,
"format": null,
"max": null,
"min": null
},
"shipping_address": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "reference",
"reference": "customer_address"
},
"updated_at": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "datetime",
"default": null,
"example": null
}
},
"type": "object",
"variants": []
},
"order_create_payload": {
"deprecated": false,
"description": null,
"discriminator": null,
"example": null,
"extends": [],
"shape": {
"order_number": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "string",
"default": null,
"example": null,
"format": null,
"max": null,
"min": null
},
"shipping_address": {
"deprecated": false,
"description": null,
"nullable": false,
"optional": false,
"type": "reference",
"reference": "customer_address"
}
},
"type": "object",
"variants": []
}
}
}TypeScript
ts
export interface Customer {
billingAddress: CustomerAddress;
createdAt: string;
id: string;
name: string;
updatedAt: string;
}
export interface CustomerAddress {
city: string;
country: string;
street: string;
}
export interface CustomerCreatePayload {
billingAddress: CustomerAddress;
name: string;
}
export interface CustomersCreateRequest {
body: CustomersCreateRequestBody;
}
export interface CustomersCreateRequestBody {
customer: CustomerCreatePayload;
}
export type CustomersCreateResponse = { status: 200; body: CustomersCreateResponseBody };
export type CustomersCreateResponseBody = { customer: Customer };
export type CustomersDestroyResponse = { status: 200; body: CustomersDestroyResponseBody };
export type CustomersDestroyResponseBody = unknown;
export type CustomersIndexResponse = { status: 200; body: CustomersIndexResponseBody };
export type CustomersIndexResponseBody = unknown;
export type CustomersShowResponse = { status: 200; body: CustomersShowResponseBody };
export type CustomersShowResponseBody = unknown;
export type CustomersUpdateResponse = { status: 200; body: CustomersUpdateResponseBody };
export type CustomersUpdateResponseBody = unknown;
export interface Order {
createdAt: string;
id: string;
orderNumber: string;
shippingAddress: CustomerAddress;
updatedAt: string;
}
export interface OrderCreatePayload {
orderNumber: string;
shippingAddress: CustomerAddress;
}
export interface OrdersCreateRequest {
body: OrdersCreateRequestBody;
}
export interface OrdersCreateRequestBody {
order: OrderCreatePayload;
}
export type OrdersCreateResponse = { status: 200; body: OrdersCreateResponseBody };
export type OrdersCreateResponseBody = { order: Order };
export type OrdersDestroyResponse = { status: 200; body: OrdersDestroyResponseBody };
export type OrdersDestroyResponseBody = unknown;
export type OrdersIndexResponse = { status: 200; body: OrdersIndexResponseBody };
export type OrdersIndexResponseBody = unknown;
export type OrdersShowResponse = { status: 200; body: OrdersShowResponseBody };
export type OrdersShowResponseBody = unknown;
export type OrdersUpdateResponse = { status: 200; body: OrdersUpdateResponseBody };
export type OrdersUpdateResponseBody = unknown;Zod
ts
import { z } from 'zod';
export const CustomerAddressSchema = z.object({
city: z.string(),
country: z.string(),
street: z.string()
});
export const CustomerSchema = z.object({
billingAddress: CustomerAddressSchema,
createdAt: z.iso.datetime(),
id: z.uuid(),
name: z.string(),
updatedAt: z.iso.datetime()
});
export const CustomerCreatePayloadSchema = z.object({
billingAddress: CustomerAddressSchema,
name: z.string()
});
export const OrderSchema = z.object({
createdAt: z.iso.datetime(),
id: z.uuid(),
orderNumber: z.string(),
shippingAddress: CustomerAddressSchema,
updatedAt: z.iso.datetime()
});
export const OrderCreatePayloadSchema = z.object({
orderNumber: z.string(),
shippingAddress: CustomerAddressSchema
});
export const CustomersIndexResponseBodySchema = z.unknown();
export const CustomersShowResponseBodySchema = z.unknown();
export const CustomersCreateRequestBodySchema = z.object({
customer: CustomerCreatePayloadSchema
});
export const CustomersCreateRequestSchema = z.object({
body: CustomersCreateRequestBodySchema
});
export const CustomersCreateResponseBodySchema = z.object({ customer: CustomerSchema });
export const CustomersUpdateResponseBodySchema = z.unknown();
export const CustomersDestroyResponseBodySchema = z.unknown();
export const OrdersIndexResponseBodySchema = z.unknown();
export const OrdersShowResponseBodySchema = z.unknown();
export const OrdersCreateRequestBodySchema = z.object({
order: OrderCreatePayloadSchema
});
export const OrdersCreateRequestSchema = z.object({
body: OrdersCreateRequestBodySchema
});
export const OrdersCreateResponseBodySchema = z.object({ order: OrderSchema });
export const OrdersUpdateResponseBodySchema = z.unknown();
export const OrdersDestroyResponseBodySchema = z.unknown();
export const CustomersIndexResponseSchema = z.object({ status: z.literal(200), body: CustomersIndexResponseBodySchema });
export const CustomersShowResponseSchema = z.object({ status: z.literal(200), body: CustomersShowResponseBodySchema });
export const CustomersCreateResponseSchema = z.object({ status: z.literal(200), body: CustomersCreateResponseBodySchema });
export const CustomersUpdateResponseSchema = z.object({ status: z.literal(200), body: CustomersUpdateResponseBodySchema });
export const CustomersDestroyResponseSchema = z.object({ status: z.literal(200), body: CustomersDestroyResponseBodySchema });
export const OrdersIndexResponseSchema = z.object({ status: z.literal(200), body: OrdersIndexResponseBodySchema });
export const OrdersShowResponseSchema = z.object({ status: z.literal(200), body: OrdersShowResponseBodySchema });
export const OrdersCreateResponseSchema = z.object({ status: z.literal(200), body: OrdersCreateResponseBodySchema });
export const OrdersUpdateResponseSchema = z.object({ status: z.literal(200), body: OrdersUpdateResponseBodySchema });
export const OrdersDestroyResponseSchema = z.object({ status: z.literal(200), body: OrdersDestroyResponseBodySchema });
export interface Customer {
billingAddress: CustomerAddress;
createdAt: string;
id: string;
name: string;
updatedAt: string;
}
export interface CustomerAddress {
city: string;
country: string;
street: string;
}
export interface CustomerCreatePayload {
billingAddress: CustomerAddress;
name: string;
}
export interface CustomersCreateRequest {
body: CustomersCreateRequestBody;
}
export interface CustomersCreateRequestBody {
customer: CustomerCreatePayload;
}
export type CustomersCreateResponse = { status: 200; body: CustomersCreateResponseBody };
export type CustomersCreateResponseBody = { customer: Customer };
export type CustomersDestroyResponse = { status: 200; body: CustomersDestroyResponseBody };
export type CustomersDestroyResponseBody = unknown;
export type CustomersIndexResponse = { status: 200; body: CustomersIndexResponseBody };
export type CustomersIndexResponseBody = unknown;
export type CustomersShowResponse = { status: 200; body: CustomersShowResponseBody };
export type CustomersShowResponseBody = unknown;
export type CustomersUpdateResponse = { status: 200; body: CustomersUpdateResponseBody };
export type CustomersUpdateResponseBody = unknown;
export interface Order {
createdAt: string;
id: string;
orderNumber: string;
shippingAddress: CustomerAddress;
updatedAt: string;
}
export interface OrderCreatePayload {
orderNumber: string;
shippingAddress: CustomerAddress;
}
export interface OrdersCreateRequest {
body: OrdersCreateRequestBody;
}
export interface OrdersCreateRequestBody {
order: OrderCreatePayload;
}
export type OrdersCreateResponse = { status: 200; body: OrdersCreateResponseBody };
export type OrdersCreateResponseBody = { order: Order };
export type OrdersDestroyResponse = { status: 200; body: OrdersDestroyResponseBody };
export type OrdersDestroyResponseBody = unknown;
export type OrdersIndexResponse = { status: 200; body: OrdersIndexResponseBody };
export type OrdersIndexResponseBody = unknown;
export type OrdersShowResponse = { status: 200; body: OrdersShowResponseBody };
export type OrdersShowResponseBody = unknown;
export type OrdersUpdateResponse = { status: 200; body: OrdersUpdateResponseBody };
export type OrdersUpdateResponseBody = unknown;OpenAPI
yml
---
openapi: 3.1.0
info:
title: "/calm_turtle"
version: 1.0.0
paths:
"/customers":
get:
operationId: customersIndex
responses:
'200':
content:
application/json:
schema: {}
description: ''
post:
operationId: customersCreate
requestBody:
content:
application/json:
schema:
properties:
customer:
"$ref": "#/components/schemas/customerCreatePayload"
type: object
required:
- customer
required: true
responses:
'200':
content:
application/json:
schema:
properties:
customer:
"$ref": "#/components/schemas/customer"
type: object
required:
- customer
description: ''
"/customers/{id}":
get:
operationId: customersShow
parameters:
- in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema: {}
description: ''
patch:
operationId: customersUpdate
parameters:
- in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema: {}
description: ''
delete:
operationId: customersDestroy
parameters:
- in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema: {}
description: ''
"/orders":
get:
operationId: ordersIndex
responses:
'200':
content:
application/json:
schema: {}
description: ''
post:
operationId: ordersCreate
requestBody:
content:
application/json:
schema:
properties:
order:
"$ref": "#/components/schemas/orderCreatePayload"
type: object
required:
- order
required: true
responses:
'200':
content:
application/json:
schema:
properties:
order:
"$ref": "#/components/schemas/order"
type: object
required:
- order
description: ''
"/orders/{id}":
get:
operationId: ordersShow
parameters:
- in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema: {}
description: ''
patch:
operationId: ordersUpdate
parameters:
- in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema: {}
description: ''
delete:
operationId: ordersDestroy
parameters:
- in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema: {}
description: ''
components:
schemas:
customer:
properties:
billingAddress:
"$ref": "#/components/schemas/customerAddress"
createdAt:
type: string
format: date-time
id:
type: string
format: uuid
name:
type: string
updatedAt:
type: string
format: date-time
type: object
required:
- billingAddress
- createdAt
- id
- name
- updatedAt
customerAddress:
properties:
city:
type: string
country:
type: string
street:
type: string
type: object
required:
- city
- country
- street
customerCreatePayload:
properties:
billingAddress:
"$ref": "#/components/schemas/customerAddress"
name:
type: string
type: object
required:
- billingAddress
- name
order:
properties:
createdAt:
type: string
format: date-time
id:
type: string
format: uuid
orderNumber:
type: string
shippingAddress:
"$ref": "#/components/schemas/customerAddress"
updatedAt:
type: string
format: date-time
type: object
required:
- createdAt
- id
- orderNumber
- shippingAddress
- updatedAt
orderCreatePayload:
properties:
orderNumber:
type: string
shippingAddress:
"$ref": "#/components/schemas/customerAddress"
type: object
required:
- orderNumber
- shippingAddress