Includes
Load associations on demand with include query parameters
API Definition
config/apis/loyal_hound.rb
rb
# frozen_string_literal: true
Apiwork::API.define '/loyal_hound' do
key_format :camel
export :openapi
export :typescript
export :zod
resources :books
endModels
app/models/loyal_hound/author.rb
rb
# frozen_string_literal: true
module LoyalHound
class Author < ApplicationRecord
has_many :books, dependent: :destroy
validates :name, presence: true
end
endDatabase Table
| Column | Type | Nullable | Default |
|---|---|---|---|
| id | string | ||
| created_at | datetime | ||
| name | string | ||
| updated_at | datetime |
app/models/loyal_hound/book.rb
rb
# frozen_string_literal: true
module LoyalHound
class Book < ApplicationRecord
belongs_to :author
has_many :reviews, dependent: :destroy
validates :title, presence: true
end
endDatabase Table
| Column | Type | Nullable | Default |
|---|---|---|---|
| id | string | ||
| author_id | string | ||
| created_at | datetime | ||
| published_on | date | ✓ | |
| title | string | ||
| updated_at | datetime |
app/models/loyal_hound/review.rb
rb
# frozen_string_literal: true
module LoyalHound
class Review < ApplicationRecord
belongs_to :book
validates :rating, presence: true
end
endDatabase Table
| Column | Type | Nullable | Default |
|---|---|---|---|
| id | string | ||
| body | text | ✓ | |
| book_id | string | ||
| created_at | datetime | ||
| rating | integer | ||
| updated_at | datetime |
Representations
app/representations/loyal_hound/book_representation.rb
rb
# frozen_string_literal: true
module LoyalHound
class BookRepresentation < Apiwork::Representation::Base
attribute :id
attribute :title, filterable: true, writable: true
attribute :published_on, sortable: true, writable: true
attribute :author_id, writable: true
attribute :created_at
attribute :updated_at
belongs_to :author
has_many :reviews
end
endapp/representations/loyal_hound/author_representation.rb
rb
# frozen_string_literal: true
module LoyalHound
class AuthorRepresentation < Apiwork::Representation::Base
attribute :id
attribute :name
end
endapp/representations/loyal_hound/review_representation.rb
rb
# frozen_string_literal: true
module LoyalHound
class ReviewRepresentation < Apiwork::Representation::Base
attribute :id
attribute :rating
attribute :body
end
endContracts
app/contracts/loyal_hound/book_contract.rb
rb
# frozen_string_literal: true
module LoyalHound
class BookContract < Apiwork::Contract::Base
representation BookRepresentation
end
endControllers
app/controllers/loyal_hound/books_controller.rb
rb
# frozen_string_literal: true
module LoyalHound
class BooksController < ApplicationController
before_action :set_book, only: %i[show update destroy]
def index
books = Book.all
expose books
end
def show
expose book
end
def create
book = Book.create(contract.body[:book])
expose book
end
def update
book.update(contract.body[:book])
expose book
end
def destroy
book.destroy
expose book
end
private
attr_reader :book
def set_book
@book = Book.find(params[:id])
end
end
endRequest Examples
List without includes
Request
http
GET /loyal_hound/booksResponse 200
json
{
"books": [
{
"id": "85b98b2f-99ee-554a-90ea-b7894ab980dc",
"title": "Pride and Prejudice",
"publishedOn": "1813-01-28",
"authorId": "c9449e5d-d293-54b7-bbeb-3e1dd9682274",
"createdAt": "2024-01-01T12:00:00.000Z",
"updatedAt": "2024-01-01T12:00:00.000Z"
},
{
"id": "54317f80-8b94-5a49-8235-e05c73330abc",
"title": "Sense and Sensibility",
"publishedOn": "1811-10-30",
"authorId": "c9449e5d-d293-54b7-bbeb-3e1dd9682274",
"createdAt": "2024-01-01T12:00:00.000Z",
"updatedAt": "2024-01-01T12:00:00.000Z"
}
],
"pagination": {
"items": 2,
"total": 1,
"current": 1,
"next": null,
"prev": null
}
}Include author
Request
http
GET /loyal_hound/books?include[author]=trueResponse 200
json
{
"books": [
{
"id": "85b98b2f-99ee-554a-90ea-b7894ab980dc",
"title": "Pride and Prejudice",
"publishedOn": "1813-01-28",
"authorId": "c9449e5d-d293-54b7-bbeb-3e1dd9682274",
"createdAt": "2024-01-01T12:00:00.000Z",
"updatedAt": "2024-01-01T12:00:00.000Z",
"author": {
"id": "c9449e5d-d293-54b7-bbeb-3e1dd9682274",
"name": "Jane Austen"
}
},
{
"id": "54317f80-8b94-5a49-8235-e05c73330abc",
"title": "Sense and Sensibility",
"publishedOn": "1811-10-30",
"authorId": "c9449e5d-d293-54b7-bbeb-3e1dd9682274",
"createdAt": "2024-01-01T12:00:00.000Z",
"updatedAt": "2024-01-01T12:00:00.000Z",
"author": {
"id": "c9449e5d-d293-54b7-bbeb-3e1dd9682274",
"name": "Jane Austen"
}
}
],
"pagination": {
"items": 2,
"total": 1,
"current": 1,
"next": null,
"prev": null
}
}Include reviews
Request
http
GET /loyal_hound/books?include[reviews]=trueResponse 200
json
{
"books": [
{
"id": "85b98b2f-99ee-554a-90ea-b7894ab980dc",
"title": "Pride and Prejudice",
"publishedOn": "1813-01-28",
"authorId": "c9449e5d-d293-54b7-bbeb-3e1dd9682274",
"createdAt": "2024-01-01T12:00:00.000Z",
"updatedAt": "2024-01-01T12:00:00.000Z",
"reviews": [
{
"id": "6865e56a-0f49-5318-85dc-dc3942d92649",
"rating": 5,
"body": "A timeless classic"
},
{
"id": "e56dbc23-e351-57f2-808e-651847b3d1c5",
"rating": 4,
"body": "Beautifully written"
}
]
}
],
"pagination": {
"items": 1,
"total": 1,
"current": 1,
"next": null,
"prev": null
}
}Include both
Request
http
GET /loyal_hound/books?include[author]=true&include[reviews]=trueResponse 200
json
{
"books": [
{
"id": "85b98b2f-99ee-554a-90ea-b7894ab980dc",
"title": "Pride and Prejudice",
"publishedOn": "1813-01-28",
"authorId": "c9449e5d-d293-54b7-bbeb-3e1dd9682274",
"createdAt": "2024-01-01T12:00:00.000Z",
"updatedAt": "2024-01-01T12:00:00.000Z",
"author": {
"id": "c9449e5d-d293-54b7-bbeb-3e1dd9682274",
"name": "Jane Austen"
},
"reviews": [
{
"id": "6865e56a-0f49-5318-85dc-dc3942d92649",
"rating": 5,
"body": "A timeless classic"
}
]
}
],
"pagination": {
"items": 1,
"total": 1,
"current": 1,
"next": null,
"prev": null
}
}Show with includes
Request
http
GET /loyal_hound/books/e56dbc23-e351-57f2-808e-651847b3d1c5?include[author]=true&include[reviews]=trueResponse 404
json
{
"status": 404,
"error": "Not Found"
}Generated Output
Introspection
json
{
"base_path": "/loyal_hound",
"enums": {
"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": {
"books": {
"actions": {
"index": {
"deprecated": false,
"description": null,
"method": "get",
"operation_id": null,
"path": "/books",
"raises": [],
"request": {
"body": {},
"query": {
"filter": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": true,
"type": "union",
"discriminator": null,
"variants": [
{
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": false,
"type": "reference",
"reference": "book_filter"
},
{
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": false,
"type": "array",
"max": null,
"min": null,
"of": {
"default": null,
"deprecated": null,
"description": null,
"example": null,
"nullable": null,
"optional": null,
"type": "reference",
"reference": "book_filter"
},
"shape": {}
}
]
},
"include": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": true,
"type": "reference",
"reference": "book_include"
},
"page": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": true,
"type": "reference",
"reference": "book_page"
},
"sort": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": true,
"type": "union",
"discriminator": null,
"variants": [
{
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": false,
"type": "reference",
"reference": "book_sort"
},
{
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": false,
"type": "array",
"max": null,
"min": null,
"of": {
"default": null,
"deprecated": null,
"description": null,
"example": null,
"nullable": null,
"optional": null,
"type": "reference",
"reference": "book_sort"
},
"shape": {}
}
]
}
}
},
"response": {
"body": {
"default": null,
"deprecated": null,
"description": null,
"example": null,
"nullable": null,
"optional": null,
"type": "union",
"discriminator": null,
"variants": [
{
"default": null,
"deprecated": null,
"description": null,
"example": null,
"nullable": null,
"optional": null,
"type": "reference",
"reference": "book_index_success_response_body"
},
{
"default": null,
"deprecated": null,
"description": null,
"example": null,
"nullable": null,
"optional": null,
"type": "reference",
"reference": "error_response_body"
}
]
},
"no_content": false
},
"summary": null,
"tags": []
},
"show": {
"deprecated": false,
"description": null,
"method": "get",
"operation_id": null,
"path": "/books/:id",
"raises": [],
"request": {
"body": {},
"query": {
"include": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": true,
"type": "reference",
"reference": "book_include"
}
}
},
"response": {
"body": {
"default": null,
"deprecated": null,
"description": null,
"example": null,
"nullable": null,
"optional": null,
"type": "union",
"discriminator": null,
"variants": [
{
"default": null,
"deprecated": null,
"description": null,
"example": null,
"nullable": null,
"optional": null,
"type": "reference",
"reference": "book_show_success_response_body"
},
{
"default": null,
"deprecated": null,
"description": null,
"example": null,
"nullable": null,
"optional": null,
"type": "reference",
"reference": "error_response_body"
}
]
},
"no_content": false
},
"summary": null,
"tags": []
},
"create": {
"deprecated": false,
"description": null,
"method": "post",
"operation_id": null,
"path": "/books",
"raises": [
"unprocessable_entity"
],
"request": {
"body": {
"book": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": false,
"type": "reference",
"reference": "book_create_payload"
}
},
"query": {
"include": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": true,
"type": "reference",
"reference": "book_include"
}
}
},
"response": {
"body": {
"default": null,
"deprecated": null,
"description": null,
"example": null,
"nullable": null,
"optional": null,
"type": "union",
"discriminator": null,
"variants": [
{
"default": null,
"deprecated": null,
"description": null,
"example": null,
"nullable": null,
"optional": null,
"type": "reference",
"reference": "book_create_success_response_body"
},
{
"default": null,
"deprecated": null,
"description": null,
"example": null,
"nullable": null,
"optional": null,
"type": "reference",
"reference": "error_response_body"
}
]
},
"no_content": false
},
"summary": null,
"tags": []
},
"update": {
"deprecated": false,
"description": null,
"method": "patch",
"operation_id": null,
"path": "/books/:id",
"raises": [
"unprocessable_entity"
],
"request": {
"body": {
"book": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": false,
"type": "reference",
"reference": "book_update_payload"
}
},
"query": {
"include": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": true,
"type": "reference",
"reference": "book_include"
}
}
},
"response": {
"body": {
"default": null,
"deprecated": null,
"description": null,
"example": null,
"nullable": null,
"optional": null,
"type": "union",
"discriminator": null,
"variants": [
{
"default": null,
"deprecated": null,
"description": null,
"example": null,
"nullable": null,
"optional": null,
"type": "reference",
"reference": "book_update_success_response_body"
},
{
"default": null,
"deprecated": null,
"description": null,
"example": null,
"nullable": null,
"optional": null,
"type": "reference",
"reference": "error_response_body"
}
]
},
"no_content": false
},
"summary": null,
"tags": []
},
"destroy": {
"deprecated": false,
"description": null,
"method": "delete",
"operation_id": null,
"path": "/books/:id",
"raises": [],
"request": {
"body": {},
"query": {
"include": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": true,
"type": "reference",
"reference": "book_include"
}
}
},
"response": {
"body": {
"default": null,
"deprecated": null,
"description": null,
"example": null,
"nullable": null,
"optional": null,
"type": null
},
"no_content": true
},
"summary": null,
"tags": []
}
},
"identifier": "books",
"parent_identifiers": [],
"path": "books",
"resources": {}
}
},
"types": {
"author": {
"deprecated": false,
"description": null,
"discriminator": null,
"example": null,
"extends": [],
"shape": {
"id": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": false,
"type": "string",
"format": null,
"max": null,
"min": null
},
"name": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": false,
"type": "string",
"format": null,
"max": null,
"min": null
}
},
"type": "object",
"variants": []
},
"author_create_payload": {
"deprecated": false,
"description": null,
"discriminator": null,
"example": null,
"extends": [],
"shape": {},
"type": "object",
"variants": []
},
"author_update_payload": {
"deprecated": false,
"description": null,
"discriminator": null,
"example": null,
"extends": [],
"shape": {},
"type": "object",
"variants": []
},
"book": {
"deprecated": false,
"description": null,
"discriminator": null,
"example": null,
"extends": [],
"shape": {
"author": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": true,
"type": "reference",
"reference": "author"
},
"author_id": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": false,
"type": "string",
"format": null,
"max": null,
"min": null
},
"created_at": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": false,
"type": "datetime"
},
"id": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": false,
"type": "string",
"format": null,
"max": null,
"min": null
},
"published_on": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": true,
"optional": false,
"type": "date"
},
"reviews": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": true,
"type": "array",
"max": null,
"min": null,
"of": {
"default": null,
"deprecated": null,
"description": null,
"example": null,
"nullable": null,
"optional": null,
"type": "reference",
"reference": "review"
},
"shape": {}
},
"title": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": false,
"type": "string",
"format": null,
"max": null,
"min": null
},
"updated_at": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": false,
"type": "datetime"
}
},
"type": "object",
"variants": []
},
"book_create_payload": {
"deprecated": false,
"description": null,
"discriminator": null,
"example": null,
"extends": [],
"shape": {
"author_id": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": false,
"type": "string",
"format": null,
"max": null,
"min": null
},
"published_on": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": true,
"optional": true,
"type": "date"
},
"title": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": false,
"type": "string",
"format": null,
"max": null,
"min": null
}
},
"type": "object",
"variants": []
},
"book_create_success_response_body": {
"deprecated": false,
"description": null,
"discriminator": null,
"example": null,
"extends": [],
"shape": {
"book": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": false,
"type": "reference",
"reference": "book"
},
"meta": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": true,
"type": "object",
"partial": false,
"shape": {}
}
},
"type": "object",
"variants": []
},
"book_filter": {
"deprecated": false,
"description": null,
"discriminator": null,
"example": null,
"extends": [],
"shape": {
"AND": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": true,
"type": "array",
"max": null,
"min": null,
"of": {
"default": null,
"deprecated": null,
"description": null,
"example": null,
"nullable": null,
"optional": null,
"type": "reference",
"reference": "book_filter"
},
"shape": {}
},
"NOT": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": true,
"type": "reference",
"reference": "book_filter"
},
"OR": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": true,
"type": "array",
"max": null,
"min": null,
"of": {
"default": null,
"deprecated": null,
"description": null,
"example": null,
"nullable": null,
"optional": null,
"type": "reference",
"reference": "book_filter"
},
"shape": {}
},
"title": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": true,
"type": "union",
"discriminator": null,
"variants": [
{
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": false,
"type": "string",
"format": null,
"max": null,
"min": null
},
{
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": false,
"type": "reference",
"reference": "string_filter"
}
]
}
},
"type": "object",
"variants": []
},
"book_include": {
"deprecated": false,
"description": null,
"discriminator": null,
"example": null,
"extends": [],
"shape": {
"author": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": true,
"type": "boolean"
},
"reviews": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": true,
"type": "boolean"
}
},
"type": "object",
"variants": []
},
"book_index_success_response_body": {
"deprecated": false,
"description": null,
"discriminator": null,
"example": null,
"extends": [],
"shape": {
"pagination": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": false,
"type": "reference",
"reference": "offset_pagination"
},
"books": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": false,
"type": "array",
"max": null,
"min": null,
"of": {
"default": null,
"deprecated": null,
"description": null,
"example": null,
"nullable": null,
"optional": null,
"type": "reference",
"reference": "book"
},
"shape": {}
},
"meta": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": true,
"type": "object",
"partial": false,
"shape": {}
}
},
"type": "object",
"variants": []
},
"book_page": {
"deprecated": false,
"description": null,
"discriminator": null,
"example": null,
"extends": [],
"shape": {
"number": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": true,
"type": "integer",
"format": null,
"max": null,
"min": 1
},
"size": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": true,
"type": "integer",
"format": null,
"max": 100,
"min": 1
}
},
"type": "object",
"variants": []
},
"book_show_success_response_body": {
"deprecated": false,
"description": null,
"discriminator": null,
"example": null,
"extends": [],
"shape": {
"book": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": false,
"type": "reference",
"reference": "book"
},
"meta": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": true,
"type": "object",
"partial": false,
"shape": {}
}
},
"type": "object",
"variants": []
},
"book_sort": {
"deprecated": false,
"description": null,
"discriminator": null,
"example": null,
"extends": [],
"shape": {
"published_on": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": true,
"type": "reference",
"reference": "sort_direction"
}
},
"type": "object",
"variants": []
},
"book_update_payload": {
"deprecated": false,
"description": null,
"discriminator": null,
"example": null,
"extends": [],
"shape": {
"author_id": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": true,
"type": "string",
"format": null,
"max": null,
"min": null
},
"published_on": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": true,
"optional": true,
"type": "date"
},
"title": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": true,
"type": "string",
"format": null,
"max": null,
"min": null
}
},
"type": "object",
"variants": []
},
"book_update_success_response_body": {
"deprecated": false,
"description": null,
"discriminator": null,
"example": null,
"extends": [],
"shape": {
"book": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": false,
"type": "reference",
"reference": "book"
},
"meta": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": true,
"type": "object",
"partial": false,
"shape": {}
}
},
"type": "object",
"variants": []
},
"error": {
"deprecated": false,
"description": null,
"discriminator": null,
"example": null,
"extends": [],
"shape": {
"issues": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": false,
"type": "array",
"max": null,
"min": null,
"of": {
"default": null,
"deprecated": null,
"description": null,
"example": null,
"nullable": null,
"optional": null,
"type": "reference",
"reference": "issue"
},
"shape": {}
},
"layer": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": false,
"type": "reference",
"reference": "layer"
}
},
"type": "object",
"variants": []
},
"error_response_body": {
"deprecated": false,
"description": null,
"discriminator": null,
"example": null,
"extends": [
"error"
],
"shape": {},
"type": "object",
"variants": []
},
"issue": {
"deprecated": false,
"description": null,
"discriminator": null,
"example": null,
"extends": [],
"shape": {
"code": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": false,
"type": "string",
"format": null,
"max": null,
"min": null
},
"detail": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": false,
"type": "string",
"format": null,
"max": null,
"min": null
},
"meta": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": false,
"type": "object",
"partial": false,
"shape": {}
},
"path": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": false,
"type": "array",
"max": null,
"min": null,
"of": {
"default": null,
"deprecated": null,
"description": null,
"example": null,
"nullable": null,
"optional": null,
"type": "string",
"format": null,
"max": null,
"min": null
},
"shape": {}
},
"pointer": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": false,
"type": "string",
"format": null,
"max": null,
"min": null
}
},
"type": "object",
"variants": []
},
"offset_pagination": {
"deprecated": false,
"description": null,
"discriminator": null,
"example": null,
"extends": [],
"shape": {
"current": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": false,
"type": "integer",
"format": null,
"max": null,
"min": null
},
"items": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": false,
"type": "integer",
"format": null,
"max": null,
"min": null
},
"next": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": true,
"optional": true,
"type": "integer",
"format": null,
"max": null,
"min": null
},
"prev": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": true,
"optional": true,
"type": "integer",
"format": null,
"max": null,
"min": null
},
"total": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": false,
"type": "integer",
"format": null,
"max": null,
"min": null
}
},
"type": "object",
"variants": []
},
"review": {
"deprecated": false,
"description": null,
"discriminator": null,
"example": null,
"extends": [],
"shape": {
"body": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": true,
"optional": false,
"type": "string",
"format": null,
"max": null,
"min": null
},
"id": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": false,
"type": "string",
"format": null,
"max": null,
"min": null
},
"rating": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": false,
"type": "integer",
"format": null,
"max": null,
"min": null
}
},
"type": "object",
"variants": []
},
"review_create_payload": {
"deprecated": false,
"description": null,
"discriminator": null,
"example": null,
"extends": [],
"shape": {},
"type": "object",
"variants": []
},
"review_update_payload": {
"deprecated": false,
"description": null,
"discriminator": null,
"example": null,
"extends": [],
"shape": {},
"type": "object",
"variants": []
},
"string_filter": {
"deprecated": false,
"description": null,
"discriminator": null,
"example": null,
"extends": [],
"shape": {
"contains": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": true,
"type": "string",
"format": null,
"max": null,
"min": null
},
"ends_with": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": true,
"type": "string",
"format": null,
"max": null,
"min": null
},
"eq": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": true,
"type": "string",
"format": null,
"max": null,
"min": null
},
"in": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": true,
"type": "array",
"max": null,
"min": null,
"of": {
"default": null,
"deprecated": null,
"description": null,
"example": null,
"nullable": null,
"optional": null,
"type": "string",
"format": null,
"max": null,
"min": null
},
"shape": {}
},
"starts_with": {
"default": null,
"deprecated": false,
"description": null,
"example": null,
"nullable": false,
"optional": true,
"type": "string",
"format": null,
"max": null,
"min": null
}
},
"type": "object",
"variants": []
}
}
}TypeScript
ts
export interface Author {
id: string;
name: string;
}
export interface Book {
author?: Author;
authorId: string;
createdAt: string;
id: string;
publishedOn: null | string;
reviews?: Review[];
title: string;
updatedAt: string;
}
export interface BookCreatePayload {
authorId: string;
publishedOn?: null | string;
title: string;
}
export interface BookCreateSuccessResponseBody {
book: Book;
meta?: Record<string, unknown>;
}
export interface BookFilter {
AND?: BookFilter[];
NOT?: BookFilter;
OR?: BookFilter[];
title?: StringFilter | string;
}
export interface BookInclude {
author?: boolean;
reviews?: boolean;
}
export interface BookIndexSuccessResponseBody {
books: Book[];
meta?: Record<string, unknown>;
pagination: OffsetPagination;
}
export interface BookPage {
number?: number;
size?: number;
}
export interface BookShowSuccessResponseBody {
book: Book;
meta?: Record<string, unknown>;
}
export interface BookSort {
publishedOn?: SortDirection;
}
export interface BookUpdatePayload {
authorId?: string;
publishedOn?: null | string;
title?: string;
}
export interface BookUpdateSuccessResponseBody {
book: Book;
meta?: Record<string, unknown>;
}
export interface BooksCreateRequest {
query: BooksCreateRequestQuery;
body: BooksCreateRequestBody;
}
export interface BooksCreateRequestBody {
book: BookCreatePayload;
}
export interface BooksCreateRequestQuery {
include?: BookInclude;
}
export interface BooksCreateResponse {
body: BooksCreateResponseBody;
}
export type BooksCreateResponseBody = BookCreateSuccessResponseBody | ErrorResponseBody;
export interface BooksDestroyRequest {
query: BooksDestroyRequestQuery;
}
export interface BooksDestroyRequestQuery {
include?: BookInclude;
}
export type BooksDestroyResponse = never;
export interface BooksIndexRequest {
query: BooksIndexRequestQuery;
}
export interface BooksIndexRequestQuery {
filter?: BookFilter | BookFilter[];
include?: BookInclude;
page?: BookPage;
sort?: BookSort | BookSort[];
}
export interface BooksIndexResponse {
body: BooksIndexResponseBody;
}
export type BooksIndexResponseBody = BookIndexSuccessResponseBody | ErrorResponseBody;
export interface BooksShowRequest {
query: BooksShowRequestQuery;
}
export interface BooksShowRequestQuery {
include?: BookInclude;
}
export interface BooksShowResponse {
body: BooksShowResponseBody;
}
export type BooksShowResponseBody = BookShowSuccessResponseBody | ErrorResponseBody;
export interface BooksUpdateRequest {
query: BooksUpdateRequestQuery;
body: BooksUpdateRequestBody;
}
export interface BooksUpdateRequestBody {
book: BookUpdatePayload;
}
export interface BooksUpdateRequestQuery {
include?: BookInclude;
}
export interface BooksUpdateResponse {
body: BooksUpdateResponseBody;
}
export type BooksUpdateResponseBody = BookUpdateSuccessResponseBody | ErrorResponseBody;
export interface Error {
issues: Issue[];
layer: Layer;
}
export type ErrorResponseBody = Error;
export interface Issue {
code: string;
detail: string;
meta: Record<string, unknown>;
path: string[];
pointer: string;
}
export type Layer = 'contract' | 'domain' | 'http';
export interface OffsetPagination {
current: number;
items: number;
next?: null | number;
prev?: null | number;
total: number;
}
export interface Review {
body: null | string;
id: string;
rating: number;
}
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 LayerSchema = z.enum(['contract', 'domain', 'http']);
export const SortDirectionSchema = z.enum(['asc', 'desc']);
export const BookFilterSchema: z.ZodType<BookFilter> = z.lazy(() => z.object({
AND: z.array(BookFilterSchema).optional(),
NOT: BookFilterSchema.optional(),
OR: z.array(BookFilterSchema).optional(),
title: z.union([z.string(), StringFilterSchema]).optional()
}));
export const AuthorSchema = z.object({
id: z.string(),
name: z.string()
});
export const BookCreatePayloadSchema = z.object({
authorId: z.string(),
publishedOn: z.iso.date().nullable().optional(),
title: z.string()
});
export const BookIncludeSchema = z.object({
author: z.boolean().optional(),
reviews: z.boolean().optional()
});
export const BookPageSchema = z.object({
number: z.number().int().min(1).optional(),
size: z.number().int().min(1).max(100).optional()
});
export const BookSortSchema = z.object({
publishedOn: SortDirectionSchema.optional()
});
export const BookUpdatePayloadSchema = z.object({
authorId: z.string().optional(),
publishedOn: z.iso.date().nullable().optional(),
title: z.string().optional()
});
export const IssueSchema = z.object({
code: z.string(),
detail: z.string(),
meta: z.record(z.string(), z.unknown()),
path: z.array(z.string()),
pointer: z.string()
});
export const OffsetPaginationSchema = z.object({
current: z.number().int(),
items: z.number().int(),
next: z.number().int().nullable().optional(),
prev: z.number().int().nullable().optional(),
total: z.number().int()
});
export const ReviewSchema = z.object({
body: z.string().nullable(),
id: z.string(),
rating: z.number().int()
});
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 BookSchema = z.object({
author: AuthorSchema.optional(),
authorId: z.string(),
createdAt: z.iso.datetime(),
id: z.string(),
publishedOn: z.iso.date().nullable(),
reviews: z.array(ReviewSchema).optional(),
title: z.string(),
updatedAt: z.iso.datetime()
});
export const ErrorSchema = z.object({
issues: z.array(IssueSchema),
layer: LayerSchema
});
export const BookCreateSuccessResponseBodySchema = z.object({
book: BookSchema,
meta: z.record(z.string(), z.unknown()).optional()
});
export const BookIndexSuccessResponseBodySchema = z.object({
books: z.array(BookSchema),
meta: z.record(z.string(), z.unknown()).optional(),
pagination: OffsetPaginationSchema
});
export const BookShowSuccessResponseBodySchema = z.object({
book: BookSchema,
meta: z.record(z.string(), z.unknown()).optional()
});
export const BookUpdateSuccessResponseBodySchema = z.object({
book: BookSchema,
meta: z.record(z.string(), z.unknown()).optional()
});
export const ErrorResponseBodySchema = ErrorSchema;
export const BooksIndexRequestQuerySchema = z.object({
filter: z.union([BookFilterSchema, z.array(BookFilterSchema)]).optional(),
include: BookIncludeSchema.optional(),
page: BookPageSchema.optional(),
sort: z.union([BookSortSchema, z.array(BookSortSchema)]).optional()
});
export const BooksIndexRequestSchema = z.object({
query: BooksIndexRequestQuerySchema
});
export const BooksIndexResponseBodySchema = z.union([BookIndexSuccessResponseBodySchema, ErrorResponseBodySchema]);
export const BooksIndexResponseSchema = z.object({
body: BooksIndexResponseBodySchema
});
export const BooksShowRequestQuerySchema = z.object({
include: BookIncludeSchema.optional()
});
export const BooksShowRequestSchema = z.object({
query: BooksShowRequestQuerySchema
});
export const BooksShowResponseBodySchema = z.union([BookShowSuccessResponseBodySchema, ErrorResponseBodySchema]);
export const BooksShowResponseSchema = z.object({
body: BooksShowResponseBodySchema
});
export const BooksCreateRequestQuerySchema = z.object({
include: BookIncludeSchema.optional()
});
export const BooksCreateRequestBodySchema = z.object({
book: BookCreatePayloadSchema
});
export const BooksCreateRequestSchema = z.object({
query: BooksCreateRequestQuerySchema,
body: BooksCreateRequestBodySchema
});
export const BooksCreateResponseBodySchema = z.union([BookCreateSuccessResponseBodySchema, ErrorResponseBodySchema]);
export const BooksCreateResponseSchema = z.object({
body: BooksCreateResponseBodySchema
});
export const BooksUpdateRequestQuerySchema = z.object({
include: BookIncludeSchema.optional()
});
export const BooksUpdateRequestBodySchema = z.object({
book: BookUpdatePayloadSchema
});
export const BooksUpdateRequestSchema = z.object({
query: BooksUpdateRequestQuerySchema,
body: BooksUpdateRequestBodySchema
});
export const BooksUpdateResponseBodySchema = z.union([BookUpdateSuccessResponseBodySchema, ErrorResponseBodySchema]);
export const BooksUpdateResponseSchema = z.object({
body: BooksUpdateResponseBodySchema
});
export const BooksDestroyRequestQuerySchema = z.object({
include: BookIncludeSchema.optional()
});
export const BooksDestroyRequestSchema = z.object({
query: BooksDestroyRequestQuerySchema
});
export const BooksDestroyResponseSchema = z.never();
export interface Author {
id: string;
name: string;
}
export interface Book {
author?: Author;
authorId: string;
createdAt: string;
id: string;
publishedOn: null | string;
reviews?: Review[];
title: string;
updatedAt: string;
}
export interface BookCreatePayload {
authorId: string;
publishedOn?: null | string;
title: string;
}
export interface BookCreateSuccessResponseBody {
book: Book;
meta?: Record<string, unknown>;
}
export interface BookFilter {
AND?: BookFilter[];
NOT?: BookFilter;
OR?: BookFilter[];
title?: StringFilter | string;
}
export interface BookInclude {
author?: boolean;
reviews?: boolean;
}
export interface BookIndexSuccessResponseBody {
books: Book[];
meta?: Record<string, unknown>;
pagination: OffsetPagination;
}
export interface BookPage {
number?: number;
size?: number;
}
export interface BookShowSuccessResponseBody {
book: Book;
meta?: Record<string, unknown>;
}
export interface BookSort {
publishedOn?: SortDirection;
}
export interface BookUpdatePayload {
authorId?: string;
publishedOn?: null | string;
title?: string;
}
export interface BookUpdateSuccessResponseBody {
book: Book;
meta?: Record<string, unknown>;
}
export interface BooksCreateRequest {
query: BooksCreateRequestQuery;
body: BooksCreateRequestBody;
}
export interface BooksCreateRequestBody {
book: BookCreatePayload;
}
export interface BooksCreateRequestQuery {
include?: BookInclude;
}
export interface BooksCreateResponse {
body: BooksCreateResponseBody;
}
export type BooksCreateResponseBody = BookCreateSuccessResponseBody | ErrorResponseBody;
export interface BooksDestroyRequest {
query: BooksDestroyRequestQuery;
}
export interface BooksDestroyRequestQuery {
include?: BookInclude;
}
export type BooksDestroyResponse = never;
export interface BooksIndexRequest {
query: BooksIndexRequestQuery;
}
export interface BooksIndexRequestQuery {
filter?: BookFilter | BookFilter[];
include?: BookInclude;
page?: BookPage;
sort?: BookSort | BookSort[];
}
export interface BooksIndexResponse {
body: BooksIndexResponseBody;
}
export type BooksIndexResponseBody = BookIndexSuccessResponseBody | ErrorResponseBody;
export interface BooksShowRequest {
query: BooksShowRequestQuery;
}
export interface BooksShowRequestQuery {
include?: BookInclude;
}
export interface BooksShowResponse {
body: BooksShowResponseBody;
}
export type BooksShowResponseBody = BookShowSuccessResponseBody | ErrorResponseBody;
export interface BooksUpdateRequest {
query: BooksUpdateRequestQuery;
body: BooksUpdateRequestBody;
}
export interface BooksUpdateRequestBody {
book: BookUpdatePayload;
}
export interface BooksUpdateRequestQuery {
include?: BookInclude;
}
export interface BooksUpdateResponse {
body: BooksUpdateResponseBody;
}
export type BooksUpdateResponseBody = BookUpdateSuccessResponseBody | ErrorResponseBody;
export interface Error {
issues: Issue[];
layer: Layer;
}
export type ErrorResponseBody = Error;
export interface Issue {
code: string;
detail: string;
meta: Record<string, unknown>;
path: string[];
pointer: string;
}
export type Layer = 'contract' | 'domain' | 'http';
export interface OffsetPagination {
current: number;
items: number;
next?: null | number;
prev?: null | number;
total: number;
}
export interface Review {
body: null | string;
id: string;
rating: number;
}
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: "/loyal_hound"
version: 1.0.0
paths:
"/books":
get:
operationId: booksIndex
parameters:
- in: query
name: filter
required: false
schema:
oneOf:
- "$ref": "#/components/schemas/bookFilter"
- items:
"$ref": "#/components/schemas/bookFilter"
type: array
- in: query
name: include
required: false
schema:
"$ref": "#/components/schemas/bookInclude"
- in: query
name: page
required: false
schema:
"$ref": "#/components/schemas/bookPage"
- in: query
name: sort
required: false
schema:
oneOf:
- "$ref": "#/components/schemas/bookSort"
- items:
"$ref": "#/components/schemas/bookSort"
type: array
responses:
'200':
content:
application/json:
schema:
"$ref": "#/components/schemas/bookIndexSuccessResponseBody"
description: Successful response
post:
operationId: booksCreate
parameters:
- in: query
name: include
required: false
schema:
"$ref": "#/components/schemas/bookInclude"
requestBody:
content:
application/json:
schema:
properties:
book:
"$ref": "#/components/schemas/bookCreatePayload"
type: object
required:
- book
required: true
responses:
'200':
content:
application/json:
schema:
"$ref": "#/components/schemas/bookCreateSuccessResponseBody"
description: Successful response
'422':
description: Unprocessable Entity
content:
application/json:
schema:
"$ref": "#/components/schemas/errorResponseBody"
"/books/{id}":
get:
operationId: booksShow
parameters:
- in: path
name: id
required: true
schema:
type: string
- in: query
name: include
required: false
schema:
"$ref": "#/components/schemas/bookInclude"
responses:
'200':
content:
application/json:
schema:
"$ref": "#/components/schemas/bookShowSuccessResponseBody"
description: Successful response
patch:
operationId: booksUpdate
parameters:
- in: path
name: id
required: true
schema:
type: string
- in: query
name: include
required: false
schema:
"$ref": "#/components/schemas/bookInclude"
requestBody:
content:
application/json:
schema:
properties:
book:
"$ref": "#/components/schemas/bookUpdatePayload"
type: object
required:
- book
required: true
responses:
'200':
content:
application/json:
schema:
"$ref": "#/components/schemas/bookUpdateSuccessResponseBody"
description: Successful response
'422':
description: Unprocessable Entity
content:
application/json:
schema:
"$ref": "#/components/schemas/errorResponseBody"
delete:
operationId: booksDestroy
parameters:
- in: path
name: id
required: true
schema:
type: string
- in: query
name: include
required: false
schema:
"$ref": "#/components/schemas/bookInclude"
responses:
'204':
description: No content
components:
schemas:
author:
properties:
id:
type: string
name:
type: string
type: object
required:
- id
- name
book:
properties:
author:
"$ref": "#/components/schemas/author"
authorId:
type: string
createdAt:
type: string
format: date-time
id:
type: string
publishedOn:
type:
- string
- 'null'
format: date
reviews:
items:
"$ref": "#/components/schemas/review"
type: array
title:
type: string
updatedAt:
type: string
format: date-time
type: object
required:
- authorId
- createdAt
- id
- publishedOn
- title
- updatedAt
bookCreatePayload:
properties:
authorId:
type: string
publishedOn:
type:
- string
- 'null'
format: date
title:
type: string
type: object
required:
- authorId
- title
bookCreateSuccessResponseBody:
properties:
book:
"$ref": "#/components/schemas/book"
meta:
properties: {}
type: object
type: object
required:
- book
bookFilter:
properties:
AND:
items:
"$ref": "#/components/schemas/bookFilter"
type: array
NOT:
"$ref": "#/components/schemas/bookFilter"
OR:
items:
"$ref": "#/components/schemas/bookFilter"
type: array
title:
oneOf:
- type: string
- "$ref": "#/components/schemas/stringFilter"
type: object
bookInclude:
properties:
author:
type: boolean
reviews:
type: boolean
type: object
bookIndexSuccessResponseBody:
properties:
pagination:
"$ref": "#/components/schemas/offsetPagination"
books:
items:
"$ref": "#/components/schemas/book"
type: array
meta:
properties: {}
type: object
type: object
required:
- pagination
- books
bookPage:
properties:
number:
type: integer
minimum: 1
size:
type: integer
minimum: 1
maximum: 100
type: object
bookShowSuccessResponseBody:
properties:
book:
"$ref": "#/components/schemas/book"
meta:
properties: {}
type: object
type: object
required:
- book
bookSort:
properties:
publishedOn:
enum:
- asc
- desc
type: string
type: object
bookUpdatePayload:
properties:
authorId:
type: string
publishedOn:
type:
- string
- 'null'
format: date
title:
type: string
type: object
bookUpdateSuccessResponseBody:
properties:
book:
"$ref": "#/components/schemas/book"
meta:
properties: {}
type: object
type: object
required:
- book
error:
properties:
issues:
items:
"$ref": "#/components/schemas/issue"
type: array
layer:
enum:
- http
- contract
- domain
type: string
type: object
required:
- issues
- layer
errorResponseBody:
"$ref": "#/components/schemas/error"
issue:
properties:
code:
type: string
detail:
type: string
meta:
properties: {}
type: object
path:
items:
type: string
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'
prev:
type:
- integer
- 'null'
total:
type: integer
type: object
required:
- current
- items
- total
review:
properties:
body:
type:
- string
- 'null'
id:
type: string
rating:
type: integer
type: object
required:
- body
- id
- rating
stringFilter:
properties:
contains:
type: string
endsWith:
type: string
eq:
type: string
in:
items:
type: string
type: array
startsWith:
type: string
type: object